> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Setup

> Connect lemlist to your AI assistant (Claude, Cursor, and more) using the Model Context Protocol

The lemlist MCP server lets you interact with lemlist directly from your AI assistant. Manage campaigns, search leads, analyze performance — all through natural conversation.

## OAuth (recommended)

With OAuth, you don't need to create an API key. Your AI client handles authentication automatically via your browser.

<Tabs>
  <Tab title="Claude Desktop">
    In Claude Desktop, open the sidebar, click the **+** icon next to **Connectors**, then choose **Add custom connector**. Set:

    * **Name**: `lemlist`
    * **URL**: `https://app.lemlist.com/mcp`

    Or add this directly to your `claude_desktop_config.json`:

    ```json theme={"theme":"dracula"}
    {
      "mcpServers": {
        "lemlist": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://app.lemlist.com/mcp"
          ]
        }
      }
    }
    ```

    `mcp-remote` handles the full OAuth flow automatically: discovery, client registration, browser-based consent, token exchange (PKCE), and token refresh.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={"theme":"dracula"}
    claude mcp add --transport http lemlist https://app.lemlist.com/mcp
    ```

    No `--header` flag needed — OAuth handles authentication automatically.
  </Tab>
</Tabs>

The first time you use a lemlist tool, your **browser will open** a consent page where you select your team and authorize access.
Tokens are managed automatically (access token: 1h, refresh token: 30 days).

## With API Key

If you prefer using an API key, first create one in lemlist:

1. Go to [app.lemlist.com](https://app.lemlist.com)
2. Navigate to **Settings > Team > Integrations**
3. Click **Generate**
4. Save your API key somewhere safe

Then configure your AI client:

<Tabs>
  <Tab title="Cursor">
    Go to **Settings > Tools & MCP > New MCP Server**, then add:

    ```json theme={"theme":"dracula"}
    {
      "mcpServers": {
        "lemlist": {
          "url": "https://app.lemlist.com/mcp",
          "headers": {
            "X-API-Key": "... YOUR API KEY ..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={"theme":"dracula"}
    claude mcp add --transport http lemlist https://app.lemlist.com/mcp \
      --header "X-API-Key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Claude Desktop (macOS/Linux)">
    Go to **Settings > Developer > Edit Config** and add to `claude_desktop_config.json`:

    ```json theme={"theme":"dracula"}
    {
      "mcpServers": {
        "lemlist": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://app.lemlist.com/mcp",
            "--header",
            "X-API-Key: ${API_KEY}"
          ],
          "env": {
            "API_KEY": "... YOUR API KEY ..."
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving. The MCP server should appear in Settings.
  </Tab>

  <Tab title="Claude Desktop (Windows)">
    ```json theme={"theme":"dracula"}
    {
      "mcpServers": {
        "lemlist": {
          "command": "C:\\PROGRA~1\\nodejs\\npx.cmd",
          "args": [
            "mcp-remote",
            "https://app.lemlist.com/mcp",
            "--header",
            "X-API-Key: ${API_KEY}"
          ],
          "env": {
            "API_KEY": "... YOUR API KEY ..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Available tools

The MCP server exposes a growing set of tools that evolve regularly. Simply ask your AI assistant what lemlist operations it can perform, and it will provide the most up-to-date list.

Current capabilities include:

* **Campaign management** — create, update, start, pause campaigns and sequences
* **Lead management** — add, search, update leads across campaigns
* **Lead sourcing** — search the 450M+ B2B database by role, industry, company size, location
* **Email enrichment** — find and verify email addresses
* **Team & stats** — view team info, campaign performance metrics
* **Webhooks** — manage event subscriptions
* **Message templates & snippets** — browse the team library and read a template or a snippet to reuse

<Note>
  Some operations (email finding, verification, phone enrichment) consume credits. Your AI assistant will warn you before using them.
</Note>

## Advanced: limit the exposed tools

By default the server exposes every tool your team has access to. If your AI assistant only needs part of lemlist, add a `?bucket=` parameter to the connector URL to expose a smaller, focused set:

```text theme={"theme":"dracula"}
https://app.lemlist.com/mcp?bucket=engagement
```

Pass several buckets by separating them with commas:

```text theme={"theme":"dracula"}
https://app.lemlist.com/mcp?bucket=prospecting,crm
```

Repeating the parameter works too, if your client writes URLs that way: `?bucket=prospecting&bucket=crm`.

| Bucket | What it covers |
| - | - |
| `core` | The always-available core on its own (see below), the smallest connector you can ask for |
| `builder` | Build and launch campaigns: sequence steps, previews, AI variables, A/B variants, senders |
| `prospecting` | Find, enrich and add leads: database search, enrichment, CSV import, lead edits |
| `crm` | Contacts, companies, lists and list membership |
| `engagement` | Inbox conversations, follow-up tasks and calls |
| `deliverability` | Domains, DNS, mailboxes, channel connection, warmup, inbox placement |
| `insights` | Reporting, watch lists, webhooks, unsubscribes, campaign folders |

Every bucket also ships with a small always-available core: campaigns and team context, settings, memory, help center search, and the generic `call_api` tool. That core is what keeps a narrowed connector usable, since anything outside your bucket stays reachable through `call_api`.

Ask for `?bucket=core` to get that core on its own. Combining it with a bucket changes nothing, since it is always included: `?bucket=core,crm` and `?bucket=crm` expose exactly the same tools.

<Warning>
  `?bucket=` controls what the server **advertises**, not what your API key is allowed to do. A narrowed connector still reaches the rest of lemlist through `call_api`, so use it to keep your assistant focused, not to restrict its access. To limit what an integration can reach, scope the API key itself.
</Warning>

<Note>
  Omit the parameter to keep the full tool list. An unrecognized bucket name is ignored, and if none of the names match the server falls back to the full list, so a typo never leaves your assistant without tools.
</Note>

***

> *That's it. No SDK, no boilerplate, no tears. Just ask.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.