# RocketReach Local MCP

A local [Model Context Protocol](https://modelcontextprotocol.io) server for RocketReach that uses the REST API and an API key. It replaces the official OAuth MCP when that endpoint is flaky or rate-limited.

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Add your API key

Store your key in your user config folder (recommended):

**Windows**

```powershell
mkdir $env:USERPROFILE\.rocketreach
Set-Content $env:USERPROFILE\.rocketreach\api_key "YOUR_API_KEY"
```

**macOS / Linux**

```bash
mkdir -p ~/.rocketreach
echo "YOUR_API_KEY" > ~/.rocketreach/api_key
chmod 600 ~/.rocketreach/api_key
```

Alternative locations (checked in order):

| Priority | Location |
|----------|----------|
| 1 | `~/.rocketreach/api_key` — plain text file |
| 2 | `~/.rocketreach/.env` — `ROCKETREACH_API_KEY=...` |
| 3 | Project `.env` — `ROCKETREACH_API_KEY=...` |
| 4 | `ROCKETREACH_API_KEY` environment variable |

Get your key from [RocketReach Account → API](https://rocketreach.co/account?section=nav_gen_api).

### 3. Connect in Cursor

Add to `%USERPROFILE%\.cursor\mcp.json`:

```json
{
  "mcpServers": {
    "rocketreach": {
      "command": "python",
      "args": ["C:\\path\\to\\RocketReach MCP\\server.py"],
      "cwd": "C:\\path\\to\\RocketReach MCP"
    }
  }
}
```

Reload MCP servers in Cursor (Settings → MCP → refresh).

## Tools

| Tool | Description | Credits |
|------|-------------|---------|
| `ping` | Liveness check | No |
| `account` | Plan, credits, rate limits | No |
| `person_search` | Search 700M+ profiles | No |
| `company_search` | Search companies | No |
| `person_lookup` | Emails/phones for a person | Yes |
| `company_lookup` | Full company profile | Yes |
| `check_person_status` | Poll async person lookups | No |

## Usage examples

### In Cursor chat

```
Check my RocketReach account credits
```

```
Find VPs of Engineering at SaaS companies in New York
```

```
Look up person id 531625233
```

### CLI tests

```bash
# Test REST client (account + sample search)
python test.py --local

# Credits and rate limits only
python test.py --usage

# Official MCP OAuth smoke test (optional)
python test.py --smoke
```

### Python client

```python
from rocketreach_mcp.client import RocketReachClient

client = RocketReachClient()

print(client.account())

results = client.person_search(
    {"current_title": ["VP Engineering"], "location": ["New York"]},
    page_size=5,
)
print(results["pagination"], len(results["profiles"]))
```

### MCP server (stdio)

```bash
python server.py
```

## Person search query examples

```json
{"name": ["Jane Doe"]}
{"current_title": ["Software Engineer"], "current_employer": ["Google"]}
{"location": ["\"San Francisco\"::~50mi"], "management_levels": ["director", "vp"]}
{"skills": ["python", "machine learning"]}
```

Use quotes inside values for exact match: `"\"IBM\""`.

## Company search query examples

```json
{"domain": ["stripe.com"]}
{"industry": ["Software"], "employees": ["100-500"]}
{"techstack": ["Salesforce"]}
```

## Person lookup

Provide one identifier:

- `id` — RocketReach profile ID from search
- `email`
- `linkedin_url`
- `name` + `current_employer`
- `npi_number`

If status is `progress`, call `check_person_status` with the profile ID.

## Project layout

```
RocketReach MCP/
├── server.py              # MCP server entrypoint
├── rocketreach_mcp/
│   ├── client.py          # REST API client
│   └── config.py          # ~/.rocketreach credential loading
├── test.py                # CLI tests
├── requirements.txt
└── README.md
```

## Notes

- Search endpoints do not consume credits; lookups do.
- The client retries on HTTP 429 using `Retry-After` or backoff.
- Keep `~/.rocketreach/api_key` out of git; it is user-local only.