Pearch.ai MCP

1# Pearch.ai MCP
2 
3MCP 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.
4 
5> [Evaluating AI Recruitment Sourcing Tools by Human Preference](https://arxiv.org/abs/2504.02463v1)
6 
7## Features
8 
9- **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.
10- **search_company_leads** — find companies and leads/contacts within them (B2B); e.g. “AI startups in SF, 50–200 employees” + “CTOs and engineering managers”.
11- **Test key by default** — works out of the box with `test_mcp_key` (masked/sample results); set your own key for full results.
12 
13## Prerequisites
14 
15- **Python 3.10+**
16- **[uv](https://docs.astral.sh/uv/)** (recommended; Linux/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`) or pip
17- **FastMCP** — install with `pip install fastmcp` or `uv add fastmcp`
18 
19## API key
20 
21Use **`test_mcp_key`** for **masked (sample) results** — no sign-up required.
22 
23For **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).
24 
25## Installation
26 
27Clone the repo, then follow the steps for your client:
28 
29```bash
30git clone https://github.com/Pearch-ai/mcp_pearch
31cd mcp_pearch
32```
33 
34### Claude Desktop
35 
36**Automatic:**
37 
38```bash
39fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
40```
41 
42Replace `test_mcp_key` with your dashboard key for full results.
43 
44If you see `bad interpreter: No such file or directory` (e.g. with conda), run:
45 
46```bash
47pip install --force-reinstall fastmcp
48```
49 
50or:
51 
52```bash
53python -m fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
54```
55 
56**Manual:** edit `~/.claude/claude_desktop_config.json` and add under `mcpServers`. Replace `/path/to/mcp_pearch` with your actual path.
57 
58With **uv**:
59 
60```json
61"Pearch.ai": {
62  "command": "uv",
63  "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/mcp_pearch/pearch_mcp.py"],
64  "env": { "PEARCH_API_KEY": "test_mcp_key" }
65}
66```
67 
68With **pip/conda** (no uv):
69 
70```json
71"Pearch.ai": {
72  "command": "python",
73  "args": ["/path/to/mcp_pearch/pearch_mcp.py"],
74  "env": { "PEARCH_API_KEY": "test_mcp_key" }
75}
76```
77 
78Ensure `fastmcp` is installed: `pip install fastmcp`.
79 
80### Cursor
81 
82**Recommended (automatic):**
83 
84```bash
85fastmcp install cursor pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key
86```
87 
88Replace `test_mcp_key` with your dashboard key for full results.
89 
90**Manual:** add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
91 
92```json
93{
94  "mcpServers": {
95    "Pearch.ai": {
96      "command": "uv",
97      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/absolute/path/to/pearch_mcp.py"],
98      "env": { "PEARCH_API_KEY": "test_mcp_key" }
99    }
100  }
101}
102```
103 
104Replace `/absolute/path/to/pearch_mcp.py` with the real path. Use `test_mcp_key` for masked results, or your dashboard key for full results.
105 
106To generate a ready snippet:
107 
108```bash
109fastmcp install mcp-json pearch_mcp.py --name "Pearch.ai"
110```
111 
112Then paste the output into `mcpServers` in `~/.cursor/mcp.json`.
113 
114### VS Code and other clients
115 
116- **VS Code:** add the same `mcpServers` block to `.vscode/mcp.json` in your workspace.
117- **Other MCP clients:** use the same `command` / `args` / `env` format in the client’s MCP config.
118 
119Generate a config snippet (defaults to `test_mcp_key`; add `--env PEARCH_API_KEY=your-key` for full results):
120 
121```bash
122fastmcp install mcp-json pearch_mcp.py --name "Pearch.ai"
123```
124 
125Paste the generated object into your client’s `mcpServers`.
126 
127## Tools
128 
129| Tool | Description |
130|------|-------------|
131| **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"*. |
132| **search_company_leads** | Find companies and leads/contacts (B2B). Example: company *"AI startups in SF, 50–200 employees"* + leads *"CTOs and engineering managers"*. |
133 
134Base URL: `PEARCH_API_URL` or per-call `base_url` (default `https://api.pearch.ai`).
135 
136## Development
137 
138```bash
139export PEARCH_API_KEY='test_mcp_key'   # or your key for full results
140fastmcp dev inspector pearch_mcp.py
141```
142 
143## Support
144 
145- [Open an issue](https://github.com/Pearch-ai/mcp_pearch/issues)
146- [f@pearch.ai](mailto:f@pearch.ai)
147 
148## License
149 
150MIT — see [LICENSE](LICENSE).
151