YourICP MCP Server

The official, open-source Model Context Protocol (MCP) server for the YourICP contact-enrichment and audience-targeting API. It lets AI assistants such as Claude enrich contacts and build audiences directly from a conversation.

Two ways to run it

	This repo (`@youricp/mcp`)	Hosted connector
Transport	`stdio`, runs on your machine	Streamable HTTP
Auth	Paste an API token	OAuth 2.0 + PKCE, browser login
Tools	Contact enrichment	Enrichment and audience building
Billing	Your existing YourICP plan	Pay-per-use, or your plan
Setup	Edit a JSON config file	Paste one URL

Use the hosted connector unless you specifically want to run the code yourself. It needs no install, stays up to date, and is the only option that exposes the audience-building tools:

Code

https://mcp.youricp.com/sse

Add it in Claude under Settings → Connectors → Add custom connector. See the connector user guide for what you can ask it.

Use this repo if you want to read or modify the code, self-host, run fully offline against your own token, or use a client that only supports stdio. It is a deliberately small reference implementation — no payment, OAuth, or hosting infrastructure required.

Tools

Tool	Description
`set_auth_token`	Set a YourICP auth token for this session
`set_token`	Deprecated alias for `set_auth_token`
`submit_lookup`	Enrich contacts by email or LinkedIn URL (returns a `jobId`)
`check_lookup`	Poll the enrichment result for a `jobId`

Requirements

Node.js 18+
A YourICP auth token — get one at app.youricp.com

Quick start (no install)

Run it directly with npx — no clone, no global install:

bash

YOURICP_AUTH_TOKEN=your_auth_token_here npx @youricp/mcp

Use with Claude Desktop

Add this to your claude_desktop_config.json — npx fetches and runs the server automatically:

config.json

{
  "mcpServers": {
    "youricp": {
      "command": "npx",
      "args": ["-y", "@youricp/mcp"],
      "env": {
        "YOURICP_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Restart Claude Desktop and the YourICP tools will appear.

Install globally (optional)

Terminal

npm install -g @youricp/mcp
YOURICP_AUTH_TOKEN=your_auth_token_here youricp-mcp

From source

bash

git clone https://github.com/youricp/mcp-server.git
cd mcp-server
npm install
YOURICP_AUTH_TOKEN=your_auth_token_here npm start

Or copy .env.example to .env and fill it in, then npm start.

Configuration

Variable	Default	Description
`YOURICP_API_URL`	`https://app.youricp.com`	Base URL of the YourICP API
`YOURICP_AUTH_TOKEN`	(none)	Your YourICP auth token
`YOURICP_API_TOKEN`	(none)	Deprecated alias for `YOURICP_AUTH_TOKEN`. Still read, but logs a deprecation notice.

Two kinds of token

YourICP uses the word "token" for two unrelated things, so this server always says which one it means:

auth token — the API credential that proves who you are. That is what YOURICP_AUTH_TOKEN and set_auth_token set.
billing token — YourICP's prepaid currency for enrichment work, where 100 billing tokens = $1.00. This reference server never touches them.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our Code of Conduct. To report a security issue, see SECURITY.md.

YourICP README