# Pearch.ai MCP

MCP server for [Pearch.AI](https://pearch.ai): natural-language search over **people** and **companies/leads** (B2B). Use it from Cursor, Claude Desktop, VS Code, or any MCP-compatible client.

> [Evaluating AI Recruitment Sourcing Tools by Human Preference](https://arxiv.org/abs/2504.02463v1)

## Features

- **search_people** — natural-language search for people (e.g. “software engineers in California with 5+ years Python”); returns candidates with optional insights and profile scoring.
- **search_company_leads** — find companies and leads/contacts within them (B2B); e.g. “AI startups in SF, 50–200 employees” + “CTOs and engineering managers”.
- **Test key by default** — works out of the box with `test_mcp_key` (masked/sample results); set your own key for full results.

## Prerequisites

- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** (recommended; Linux/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`) or pip
- **FastMCP** — install with `pip install fastmcp` or `uv add fastmcp`

## API key

Use **`test_mcp_key`** for **masked (sample) results** — no sign-up required.

For **full, unmasked results**, get an API key from the [Pearch.ai Dashboard](https://platform.pearch.ai/dashboard) and set it as `PEARCH_API_KEY` in your MCP config (see Installation below).

## Installation

Clone the repo, then follow the steps for your client:

```bash
git clone https://github.com/Pearch-ai/mcp_pearch
cd mcp_pearch
```

### Claude Desktop

**Automatic:**

```bash
fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
```

Replace `test_mcp_key` with your dashboard key for full results.

If you see `bad interpreter: No such file or directory` (e.g. with conda), run:

```bash
pip install --force-reinstall fastmcp
```

or:

```bash
python -m fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
```

**Manual:** edit `~/.claude/claude_desktop_config.json` and add under `mcpServers`. Replace `/path/to/mcp_pearch` with your actual path.

With **uv**:

```json
"Pearch.ai": {
  "command": "uv",
  "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/mcp_pearch/pearch_mcp.py"],
  "env": { "PEARCH_API_KEY": "test_mcp_key" }
}
```

With **pip/conda** (no uv):

```json
"Pearch.ai": {
  "command": "python",
  "args": ["/path/to/mcp_pearch/pearch_mcp.py"],
  "env": { "PEARCH_API_KEY": "test_mcp_key" }
}
```

Ensure `fastmcp` is installed: `pip install fastmcp`.

### Cursor

**Recommended (automatic):**

```bash
fastmcp install cursor pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
```

Replace `test_mcp_key` with your dashboard key for full results.

**Manual:** add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "Pearch.ai": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/absolute/path/to/pearch_mcp.py"],
      "env": { "PEARCH_API_KEY": "test_mcp_key" }
    }
  }
}
```

Replace `/absolute/path/to/pearch_mcp.py` with the real path. Use `test_mcp_key` for masked results, or your dashboard key for full results.

To generate a ready snippet:

```bash
fastmcp install mcp-json pearch_mcp.py --name "Pearch.ai"
```

Then paste the output into `mcpServers` in `~/.cursor/mcp.json`.

### VS Code and other clients

- **VS Code:** add the same `mcpServers` block to `.vscode/mcp.json` in your workspace.
- **Other MCP clients:** use the same `command` / `args` / `env` format in the client’s MCP config.

Generate a config snippet (defaults to `test_mcp_key`; add `--env PEARCH_API_KEY=your-key` for full results):

```bash
fastmcp install mcp-json pearch_mcp.py --name "Pearch.ai"
```

Paste the generated object into your client’s `mcpServers`.

## Tools

| Tool | Description |
|------|-------------|
| **search_people** | Natural-language search for people or follow-up on a thread. Example: *"software engineers in California with 5+ years Python"*, *"senior ML researchers in Berlin"*. |
| **search_company_leads** | Find companies and leads/contacts (B2B). Example: company *"AI startups in SF, 50–200 employees"* + leads *"CTOs and engineering managers"*. |

Base URL: `PEARCH_API_URL` or per-call `base_url` (default `https://api.pearch.ai`).

## Development

```bash
export PEARCH_API_KEY='test_mcp_key'   # or your key for full results
fastmcp dev inspector pearch_mcp.py
```

## Support

- [Open an issue](https://github.com/Pearch-ai/mcp_pearch/issues)
- [f@pearch.ai](mailto:f@pearch.ai)

## License

MIT — see [LICENSE](LICENSE).