<!-- mcp-name: com.youricp/mcp-server -->

# YourICP MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-compatible-brightgreen.svg)](https://modelcontextprotocol.io)

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