<p align="center"><img src="assets/logo.png" width="72" height="72" alt="EvenLeads"></p>

# EvenLeads MCP server

Find customers for your business from inside your AI assistant.

Tell ChatGPT, Claude or Cursor what you sell. EvenLeads searches recent public posts (Reddit, LinkedIn, X and more) for people who are asking for it, shows the best matches with the reason each one fits, and drafts a first message that you send yourself.

<p align="center"><img src="assets/leads-in-chat.jpg" width="640" alt="Lead cards shown in the chat, each with a match score, the reason it fits and buttons to draft a message or open the post (example data)"></p>

```
https://dash.evenleads.com/api/mcp
```

It is a hosted MCP server (Streamable HTTP, OAuth). There is nothing to install or run.

## Connect it

| App | How |
| --- | --- |
| **Claude** (web, desktop, mobile) | Settings → Connectors → Add custom connector → paste `https://dash.evenleads.com/api/mcp` → Authentication: **Sign in when needed** → Add |
| **ChatGPT** | Plugins → Add custom MCP server → paste `https://dash.evenleads.com/api/mcp/chatgpt` |
| **Claude Code** | `claude mcp add --transport http evenleads https://dash.evenleads.com/api/mcp` then `/mcp` to sign in |
| **Cursor** | [Add to Cursor](https://cursor.com/en/install-mcp?name=evenleads&config=eyJ1cmwiOiJodHRwczovL2Rhc2guZXZlbmxlYWRzLmNvbS9hcGkvbWNwIn0%3D) |
| **VS Code** | [Add to VS Code](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522evenleads%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%2F%2Fdash.evenleads.com%2Fapi%2Fmcp%2522%257D) |
| **Anything else** | Add a remote MCP server with the address above |

Config file form, for apps that use one:

```json
{
  "mcpServers": {
    "evenleads": { "url": "https://dash.evenleads.com/api/mcp" }
  }
}
```

The first time a tool needs your account, your app opens the EvenLeads sign-in. No account yet? That screen lets you create a free one and brings you back to the chat. A free account includes one search for your own business; no card is needed.

### Claude Code plugin

Adds the server plus a skill that teaches Claude the whole flow (search, show leads, draft, mark as sent):

```
claude plugin marketplace add EcMarius/evenleads-mcp
claude plugin install evenleads@evenleads
```

### Apps that only support local (stdio) servers

```json
{
  "mcpServers": {
    "evenleads": {
      "command": "npx",
      "args": ["-y", "evenleads-mcp"],
      "env": { "EVENLEADS_API_KEY": "your key from EvenLeads > Settings > API" }
    }
  }
}
```

`evenleads-mcp` is a small bridge with no dependencies: it passes each request to the hosted server and returns the answer. Without a key it can still search public hiring requests.

## What to ask

- *Find customers for my business. I run a bookkeeping service for freelancers and small online shops.*
- *Check how the search is going and show me the leads it found.*
- *Draft a private message for the first lead.*
- *Show my leads from Reddit with a score of 8 or more.*
- *Who is looking for a Shopify developer right now?* (works without signing in)
- *How many searches do I have left?*

## Tools

| Tool | What it does | Sign-in |
| --- | --- | --- |
| `find_customers` | Saves a campaign from your description and starts a search for people asking for what you sell. Returns a search id right away. | yes |
| `get_search_status` | Progress of a search and the leads found so far, best matches first. | yes |
| `get_my_leads` | Your leads, with filters for campaign, platform, score and status. | yes |
| `draft_reply` | Writes a private message or public reply for one lead and returns the link to send it yourself. | yes |
| `update_lead_status` | Marks a lead as contacted, not a fit, closed or new. | yes |
| `list_my_campaigns` | Your campaigns and what each one looks for. | yes |
| `get_account` | What is left in your plan: searches, campaigns, reply drafts, stored leads. | yes |
| `find_hiring_requests` | Recent public posts where someone asks to hire a freelancer or agency. | no |
| `list_niches` | The freelance and agency services EvenLeads tracks. | no |
| `search`, `fetch` | The same hiring requests in the shape research-style clients expect. | no |

Every tool declares `readOnlyHint`, `destructiveHint` and `openWorldHint`, an `outputSchema`, and returns `structuredContent` next to plain text. Nothing is ever sent to a lead for you: drafts come with a link, and you press send.

In ChatGPT and Claude the lead tools render an interactive view (MCP Apps, `ui://evenleads/leads.html`) with live search progress, lead cards and an editable draft. In other clients the same results arrive as text.

## Sign-in and data

- OAuth 2.1 with PKCE. Client ID Metadata Documents and Dynamic Client Registration are both supported; discovery is at `/.well-known/oauth-protected-resource/api/mcp`.
- Scopes: `leads:read` (campaigns, leads, account) and `leads:write` (start searches, write drafts, update leads).
- Your assistant sees the public post of each lead (title, text, link, community, author's public name), the match score and reason, your campaign names and your plan limits. It never sees your password, billing details or connected social accounts.
- Disconnect an app at any time under **Connected AI apps**: https://dash.evenleads.com/settings/ai-apps
- [Privacy policy](https://evenleads.com/privacy) · [Terms](https://evenleads.com/terms)

## This repository

| Path | For |
| --- | --- |
| `server.json` | The official MCP Registry entry (`com.evenleads/evenleads`) |
| `bin/evenleads-mcp.js`, `package.json` | The `evenleads-mcp` npm package (stdio bridge) |
| `.claude-plugin/`, `.mcp.json`, `skills/` | The Claude plugin and its marketplace entry |
| `plugin.json`, `mcp.json`, `skills/`, `assets/` | The ChatGPT plugin package (`scripts/build-openai-zip.sh` zips it) |

The server itself is part of the EvenLeads application and is not in this repository.

## Help

Setup guide: https://dash.evenleads.com/ai-assistants

Something not working? Open an issue here or write to contact@evenleads.com.

## License

MIT