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:
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:
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:
{
"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)
npm install -g @youricp/mcp
YOURICP_AUTH_TOKEN=your_auth_token_here youricp-mcp
From source
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_TOKENandset_auth_tokenset. - 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.
License
MIT © YourICP