mcp

<p align="center">
  <img src="logo.png" alt="Leadbay MCP" width="200">
</p>

<h1 align="center">Leadbay MCP</h1>
<p align="center"><strong>Leadbay MCP connects your AI assistant to your Leadbay account, so you can work your leads by simply asking.</strong></p>
<p align="center">Pull leads, qualify them, draft outreach, and log activity — in plain language. Your assistant acts on your real Leadbay data, with your permissions, just as you would in the app.</p>
<p align="center">Everything is personalized — nothing to configure. Leadbay runs advanced AI on your website and market data to source and score leads against your target profile, so outreach becomes meaningful connection instead of senseless spamming.</p>
<p align="center">Tell your assistant which leads to prospect, connect your channels, and it sources contacts from Leadbay and handles outreach on your behalf. Enjoy the outreach you no longer have to do.
</p>

> **MCP** stands for *Model Context Protocol* — an open standard that lets AI assistants like Claude securely connect to external tools and data. This server is open source and lives at [github.com/leadbay/mcp](https://github.com/leadbay/mcp).

---

## How Leadbay thinks (mental model for your agent)

- **Inbox, not a database.** Each day your user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently — some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; acting on leads does.
- **Two scoring layers.** Every lead ships with a basic `score` (firmographic — already decent, usually correlates with AI). Roughly the top 10 of each batch are also AI-qualified (targeted web research + qualification questions → `ai_agent_lead_score`). Leads below the top 10 aren't worse — the system is saving resources. The agent can request deeper qualification (`leadbay_bulk_qualify_leads`) or contact enrichment (`leadbay_enrich_titles`) on any lead that looks worth it.
- **Daily rhythm.** The agent works best as a daily check-in: pull fresh leads, skim the auto-qualified top, deepen 1-3 promising ones, propose outreach, then log what actually got sent via `leadbay_report_outreach`. If your host supports scheduling, set up a daily run.

---

# For users

Get Leadbay MCP running inside your AI assistant in a couple of minutes. No coding required.

> **New to Leadbay?** The friendly, screenshot-driven walkthrough — what a lens is, how scoring works, and the full MCP setup for every assistant — lives in the **[Leadbay user guide](https://docs.leadbay.ai/leadbay-mcp/what-is-leadbay-mcp)**. This README is the technical companion.

> **No Leadbay account yet?** [Create one here](https://wow.leadbay.ai/?register=true) first — you'll need it to sign in during setup.

## Connect on the web (no install)

If you use Claude on the web, Claude Desktop, or ChatGPT, the fastest path is a **custom connector** — no terminal, no tokens to copy. Add one URL and sign in with your browser:

- **Name:** `Leadbay`
- **URL:** `https://mcp.leadbay.app/mcp`  — one URL for every region (`/fr/mcp` remains a compatibility alias)
- **On ChatGPT, use `https://mcp.leadbay.app/chatgpt/mcp` instead.** Same server, same sign-in, same leads — but the assistant cannot generate a top-up link or open your billing page there, because the OpenAI app directory does not allow an app to sell credits. Buy credits or change your plan in your Leadbay account instead.

In Claude: **Settings → Connectors → + → Add custom connector**, paste the URL, then open the connector and **Connect**. Sign in with Leadbay, click **Approve**, and you're linked. The server handles OAuth in-app; updates are automatic — you never touch a config file.

## Install in Claude Desktop (one-click bundle)

Prefer a bundled desktop extension? Grab the one-click file.

**1. Download the extension**

👉 **[Download the latest Leadbay MCP for Claude (.dxt)](https://github.com/leadbay/mcp/releases/latest)**

On the releases page, click the file ending in **`.dxt`** to download it.

**2. Install it**

Double-click the downloaded `.dxt` file. Claude opens and shows an install dialog — click **Install**, and you're done.

**If the double-click doesn't open Claude**, install it manually:

1. Open Claude and go to your **profile → Settings → Extensions**.
2. Open **Advanced settings**.
3. Choose **Install extension…** and select the `.dxt` file you downloaded.

**3. Sign in**

Claude will prompt you to connect Leadbay. Sign in with your Leadbay account and you're ready — just ask your agent for leads.

## Using a local assistant?

Leadbay MCP also works with Claude Code, Claude Desktop, Cursor, and Codex. The **universal installer** sets everything up for you and lets you sign in with Leadbay.

Requires [Node.js 22+](https://nodejs.org). Then run:

```bash
npx -y -p @leadbay/mcp@latest installer
```

It opens in your browser where you click **Sign in with Leadbay**, then pick which assistants to connect. Works on macOS, Windows, and Linux.

**To uninstall**, run the same installer with `--uninstall`:

```bash
npx -y -p @leadbay/mcp@latest installer --uninstall
```

It opens an uninstall window showing only the assistants that have Leadbay connected — pick the ones to remove and click **Remove selected**. It only removes Leadbay; your other settings and connections are left untouched.

## Ask for your first leads

Open a new conversation and describe the outcome — you never name a tool, just say what you want, the way you'd ask a colleague:

> *Show me today's leads and tell me which two are worth opening first.*

A successful first reply is a **ranked table of prospects**, not a wall of text: each row has a fit score, a one-line why-it-fits, and the best contact to reach. Then keep going:

> *Research the top one — is it a fit for us?*

> *Draft me an outreach email to them.*

> *I just emailed them. Log it as outreach.*

---

# For developers

Everything below is for contributors and anyone running Leadbay MCP from source or wiring it into automation.

## Install a local version with the custom installer

To run your local checkout (instead of the published package), first build it from source:

```bash
pnpm install
pnpm prompts:build
pnpm -r build
```

Then point the installer at your freshly built version with `--local`:

```bash
pnpm --filter @leadbay/mcp installer -- --local
```

`--local` registers the MCP client(s) against the build in your working tree rather than `@leadbay/mcp@latest`. OAuth is handled automatically — you don't need to pass `--oauth`. The installer asks per-target before writing anything.

## All install methods

Every supported way to connect Leadbay MCP:

| Method | Command / action | Platforms | Notes |
|--------|------------------|-----------|-------|
| **Hosted connector (no install)** | Add custom connector → `https://mcp.leadbay.app/mcp` (all regions) | Claude web / Desktop | Browser OAuth in-app. Nothing to install; auto-updates. |
| **Hosted connector — ChatGPT** | Add custom connector → `https://mcp.leadbay.app/chatgpt/mcp` | ChatGPT | Same server; the top-up and billing tools are not registered (OpenAI directory rule). |
| **`.dxt` / `.mcpb` bundle** | Download from [Releases](https://github.com/leadbay/mcp/releases/latest), double-click → **Install** | Claude Desktop | One-click desktop extension. |
| **Guided installer (GUI)** | `npx -y -p @leadbay/mcp@latest installer` | macOS, Windows, Linux | Browser wizard: sign in with Leadbay, pick clients. Works for everyone. |
| **Local dev build** | `pnpm --filter @leadbay/mcp installer -- --local` | macOS, Windows, Linux | Registers clients against your local build. OAuth automatic. Build from source first (above). |
| **Claude Code plugin marketplace** | `/plugin marketplace add leadbay/mcp` then `/plugin install leadbay@leadbay-mcp` | Claude Code | Registers the MCP server **and** installs auto-triggering skills. |

### What each installer writes per client

The GUI/CLI installers only touch clients that are actually installed on the machine:

| Client | Installer behavior |
|--------|--------------------|
| Claude Code | Registers/removes `leadbay` with `claude mcp add/remove --scope user` |
| Claude Desktop | Writes/removes only the `mcpServers.leadbay` entry in `claude_desktop_config.json` |
| Cursor | Writes/removes only the `mcpServers.leadbay` entry in Cursor's MCP config |
| Codex | Writes/removes only the `[mcp_servers.leadbay]` block in `~/.codex/config.toml` and the Leadbay-managed shell export block |

### Claude Code plugin marketplace

```bash
/plugin marketplace add leadbay/mcp
```

```bash
/plugin install leadbay@leadbay-mcp
```

Claude Code prompts for Leadbay auth/config. Registers the MCP server **and** installs a set of skills that auto-trigger on natural-language asks — including `leadbay_daily_check_in` ("get my leads today"), `leadbay_research_a_domain` ("research acme.com"), `leadbay_followup_check_in`, `leadbay_qualify_top_n`, `leadbay_refine_audience`, `leadbay_log_outreach`, `leadbay_import_file`, `leadbay_plan_tour_in_city`, `leadbay_prospecting_overview`, `leadbay_extend_my_lens`, `leadbay_setup_team_prospecting`, `leadbay_build_campaign`, and `leadbay_work_campaign`. Each `SKILL.md` is generated by `@leadbay/promptforge` from the same source as the MCP prompts, so the two surfaces never drift.

### Uninstall

```bash
npx -y -p @leadbay/mcp@latest installer --uninstall
```

Opens the uninstall wizard — only shows clients that already have Leadbay MCP configured. De-registers Claude Code, strips the JSON stanza from Claude Desktop / Cursor configs, removes the `[mcp_servers.leadbay]` TOML block from Codex, and strips the managed `export LEADBAY_*` block from `~/.zshrc` / `~/.bashrc`. Uninstall is scoped to Leadbay — it never rewrites unrelated client settings or removes other MCP servers.

## Tools

Your assistant calls these on your behal