@youricp/mcp

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.

This is a reference implementation using the stdio transport, designed to run locally with clients like Claude Desktop. It authenticates with a plain API token — no payment, OAuth, or hosting infrastructure required. For the fully hosted remote connector (Streamable HTTP, OAuth 2.0 + PKCE, pay-per-use), see app.youricp.com.

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_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.

License

MIT © YourICP