<p align="center"><img src="logo.png" width="96" alt="FindLeadEmails logo"></p>

# FindLeadEmails MCP server

Find and verify B2B work emails from your AI assistant: single lookups or bulk lists, with deliverability checks.

This repository holds setup docs and config for the hosted FindLeadEmails MCP server. There is no code to install: the server is remote.

- **URL:** `https://www.findleademails.com/api/mcp` (Streamable HTTP)
- **Auth:** sign in with OAuth 2.1 in clients that support it (Claude, ChatGPT, Codex, VS Code, Cursor, Claude Code, Gemini CLI, and others): add the URL with no header and approve in the browser. Or send `Authorization: Bearer YOUR_API_KEY`. Listing tools (`initialize`, `tools/list`) needs neither.
- **API key** (only if you don't use OAuth): sign in and create one at https://www.findleademails.com/developers?utm_source=github. It is shown once; rotate it there if lost. Never commit it.

Use the `www` host. `https://findleademails.com` redirects, and some clients drop the `Authorization` header when following that redirect.

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=findleademails&config=eyJ1cmwiOiJodHRwczovL3d3dy5maW5kbGVhZGVtYWlscy5jb20vYXBpL21jcCJ9)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square)](https://vscode.dev/redirect/mcp/install?name=findleademails&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//www.findleademails.com/api/mcp%22%7D)

Both buttons add the server URL only. Approve the OAuth sign-in in your browser the first time a tool runs.

## Tools

| Tool | What it does | Credits |
|---|---|---|
| `find_email` | Find and verify one person's work email from `first_name`, `last_name`, `company_domain` (or a LinkedIn company page URL). | 1 only when the mailbox is verified |
| `verify_email` | Check one `email` you already have. | 1 only when confirmed valid |
| `find_emails_bulk` | Find and verify a batch in one synchronous call (capped; returns `batch_too_large` above the cap). | 1 per verified result |
| `create_job` | Queue a large list for background processing; returns a job id. | Reserves 1 per row, refunds unused |
| `get_job_status` | Progress and per-outcome counters for a job. | Free |
| `get_job_results` | A page of per-row results (page with `cursor` until `next_cursor` is null). Works while running. | Free |

Pricing: misses, catch-alls, predicted results and repeat lookups are free; you pay only for verified emails. Credits never expire. See https://www.findleademails.com/docs/mcp?utm_source=github#credits.

## Sign in with OAuth

The server supports OAuth 2.1 with PKCE (S256), Client ID Metadata Documents, and Dynamic Client Registration. In a client that supports OAuth, add the URL with no `Authorization` header and approve access in your browser. No API key needed.

- **Claude** (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector. Paste `https://www.findleademails.com/api/mcp`, choose "Sign in when needed", and keep "Use Claude's published identity".
- **ChatGPT and Codex:** add the server with the URL above and choose OAuth as the authentication method.
- **Claude Code:**

  ```bash
  claude mcp add --transport http findleademails https://www.findleademails.com/api/mcp
  ```

  Then run `/mcp` in Claude Code, select `findleademails`, and choose Authenticate.
- **VS Code and Cursor:** add the URL only, with no `headers` (or use the install buttons above). The client opens the sign-in page when needed.
- **Gemini CLI:** after installing the extension, run `/mcp auth findleademails`.

Prefer an API key? Use the snippets below.

## Setup with an API key

Replace `YOUR_API_KEY` with your key in every snippet.

### Cursor

For OAuth, use the Add to Cursor button above. For an API key, add this by hand to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). The same file is in this repo as [`.mcp.json`](.mcp.json).

```json
{
  "mcpServers": {
    "findleademails": {
      "url": "https://www.findleademails.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

To keep the key out of the file, use `"Bearer ${env:FINDLEADEMAILS_API_KEY}"`.

### Claude Code

```bash
claude mcp add --transport http findleademails https://www.findleademails.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

### Claude Desktop

Claude Desktop needs the `mcp-remote` bridge (Node.js 18+). In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "findleademails": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.findleademails.com/api/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
    }
  }
}
```

### VS Code

`.vscode/mcp.json`. VS Code prompts for the key and stores it securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "findleademails-api-key",
      "description": "Paste your FindLeadEmails API key.",
      "password": true
    }
  ],
  "servers": {
    "findleademails": {
      "type": "http",
      "url": "https://www.findleademails.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:findleademails-api-key}"
      }
    }
  }
}
```

### Windsurf

`mcp_config.json` (open it from the Cascade panel's actions menu; on macOS/Linux `~/.config/devin/mcp_config.json`, on Windows `%APPDATA%\devin\mcp_config.json`):

```json
{
  "mcpServers": {
    "findleademails": {
      "serverUrl": "https://www.findleademails.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Cline

Ask Cline to install this server from this repo (it follows [`llms-install.md`](llms-install.md)), or add to `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "findleademails": {
      "type": "streamableHttp",
      "url": "https://www.findleademails.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Gemini CLI

```bash
gemini extensions install https://github.com/findleademails/findleademails-mcp
```

The CLI asks for your API key during install and stores it in the system keychain. Change it later with `gemini extensions config findleademails`.

### Perplexity

Pro, Max or Enterprise: Connectors → add a custom remote connector and choose the authentication option your plan offers. With an API key:

```
URL: https://www.findleademails.com/api/mcp
Header: Authorization: Bearer YOUR_API_KEY
```

### Grok

On grok.com: Connectors → New Connector → Custom, enter the server URL, and paste the API key when asked for authentication. Business and Enterprise workspaces need an admin to provision custom connectors first.

Grok CLI:

```bash
grok mcp add --transport http findleademails https://www.findleademails.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

xAI API (the key goes in `authorization` without the word Bearer):

```json
{
  "type": "mcp",
  "server_url": "https://www.findleademails.com/api/mcp",
  "server_label": "findleademails",
  "authorization": "YOUR_API_KEY"
}
```

### Other clients

A client that supports OAuth only needs the URL. Any client that takes a remote URL plus headers: use the Cursor JSON above, adjusted to that client's key names.

## Try it

```bash
curl https://www.findleademails.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

A tool call without a key or OAuth token returns HTTP 401 `invalid_token` (with a `WWW-Authenticate` header pointing OAuth clients to sign-in) and nothing is charged. A POST without `Accept: application/json, text/event-stream` returns 406.

## Links

- Docs: https://www.findleademails.com/docs/mcp?utm_source=github
- REST API docs: https://www.findleademails.com/docs?utm_source=github
- API keys: https://www.findleademails.com/developers?utm_source=github
- Pricing: https://www.findleademails.com/pricing?utm_source=github
- Contact: hi@findleademails.com

## License

MIT. See [LICENSE](LICENSE).

— The FindLeadEmails team