# YourICP MCP Server [](LICENSE) [](https://modelcontextprotocol.io) [](https://m8ven.ai/mcp/youricp-mcp-server-19i1ow?s=readme) The official, open-source [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [YourICP](https://app.youricp.com) 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](https://mcp.youricp.com/docs) 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](https://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: ```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) ```bash 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](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). To report a security issue, see [SECURITY.md](SECURITY.md). ## License [MIT](LICENSE) © YourICP