The lemlist MCP server lets AI clients (like Claude Desktop, Claude Code, or Cursor) securely interact with your lemlist workspace through MCP (JSON-RPC over HTTP). You can authenticate either with OAuth (no API key) or with an API key, depending on your environment and security preferences.

Learning Objective

By the end of this tutorial, you’ll know how to connect the lemlist MCP server to Claude Desktop, Claude Code, or Cursor using either OAuth (recommended when available) or an API key, and verify that the connection works.

Why This Matters

Once the lemlist MCP server is connected, your AI client can help you audit campaigns, create or update sequences, and manage leads—without switching between tools. OAuth reduces secret management overhead, while API keys provide a straightforward option for environments that don’t support OAuth flows.

Prerequisites

You have a lemlist account and access to the team/workspace you want to connect.
You have one of the supported clients installed: Claude Desktop, Claude Code, or Cursor.
If using Claude Desktop with npm, you have Node.js available (so npx works).
If using API key auth, you can generate an API key in lemlist.

Phase 1: Choose your authentication method

Option A (Recommended): OAuth (no API key needed)

With OAuth, you don’t need to create or store an API key. Your LLM client completes authentication through your browser, including consent, token exchange (PKCE), and token refresh.

First use behavior: the first time you call a lemlist tool, your browser opens a consent page where you select your team and authorize access.
Token handling: managed automatically (access token ~1 hour, refresh token ~30 days).

Option B: API key

If your environment requires it, you can authenticate using an API key via an HTTP header (X-API-Key).

Phase 2: Set up lemlist MCP with OAuth

Claude Desktop (OAuth)

Open your Claude Desktop configuration file: claude_desktop_config.json.
Add the following MCP server configuration:

{"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.

Save the file and restart Claude Desktop.
Trigger any lemlist tool call; your browser should open a consent page.
Select your lemlist team/workspace and approve access.

Claude Code (OAuth)

Run the following command:

claude mcp add --transport http lemlist https://app.lemlist.com/mcp

No --header flag is needed—OAuth handles authentication automatically.

The first time you use a lemlist tool, complete the browser consent flow (select team, authorize).

Phase 3: Set up lemlist MCP with an API key

Step 1: Generate your lemlist API key

Log in to lemlist: https://app.lemlist.com
Go to Settings → Team → Integrations.
Click Generate to create an API key.
Store the key somewhere safe (for example, a vault/password manager). You may not be able to view it again.

Step 2: Choose your client configuration

Cursor (API key)

Open Settings → Tools & MCP.
Create a New MCP Server.
Add a lemlist block like the example below (replace the API key):

{"mcpServers": {"lemlist": {"url": "https://app.lemlist.com/mcp","headers": {"X-API-Key": "... YOUR API KEY ..."}}}}

Claude Code (API key)

Run the following command (replace the API key value):

claude mcp add --transport http lemlist https://app.lemlist.com/mcp --header "X-API-Key: PUTYOURAPIKEY"

Claude Desktop with npm (API key)

Claude Desktop can be configured to run the MCP server via npx and pass the API key through an environment variable.

Open Claude Desktop settings and navigate to Developer → Edit Config.
In claude_desktop_config.json, add a lemlist MCP server block (replace the API key):

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

Claude Desktop on Windows (API key)

If npx isn’t found on Windows, point directly to npx.cmd:

{"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 ..."}}}

Restart Claude Desktop. The lemlist MCP server should now appear in settings.

Phase 4: Verify your setup

Open your AI client and start a new chat.
Ask the assistant what lemlist tools are available (tool availability may change over time).
Run a simple “read-only” action first (for example, listing campaigns) before attempting changes.

Tip: If you’re using OAuth, your first tool call should trigger a browser consent screen. If you don’t see it, jump to the troubleshooting section below.

Practical Application: Create a specialized “lemlist agent” command (Claude Code)

If you use Claude Code, you can create a custom command that “loads” a lemlist-focused agent prompt. This is helpful if you frequently use lemlist for campaign audits, lead sourcing, and sequence optimization.

Create a file named lemlist-agent.md in your .claude/commands folder.
Paste your agent instructions into that file.
In Claude Code, type /lemlist-agent to activate the agent.

Common agent workflows to include:

Campaign audit: list campaigns → pull stats (30/90 days) → identify bottlenecks → propose fixes.
New campaign creation: define ICP → draft a 3–4 email sequence → configure timing → guide lead import.
Lead sourcing: define ICP filters → search lemleads → validate sample results → enrich cautiously → dedupe and import.

Troubleshooting & Pitfalls

Issue: OAuth consent page doesn’t open

Root cause: The tool call didn’t trigger an OAuth flow, pop-ups are blocked, or the MCP server wasn’t registered correctly.
Fix:
- Trigger a lemlist tool call again from the client.
- Temporarily allow pop-ups for your AI client/browser.
- Re-check the MCP endpoint: https://app.lemlist.com/mcp.
- Restart the client after config changes.

Issue: Authentication fails with API key

Root cause: Missing/incorrect X-API-Key header or the key is expired/revoked.
Fix:
- Confirm the header name is exactly X-API-Key (case and punctuation matter).
- Regenerate the API key in lemlist if needed and update your config.
- For Claude Desktop, confirm your env variable matches (API_KEY).

Issue: Claude Desktop doesn’t show the MCP server

Root cause: Invalid JSON, wrong file location, or Claude needs a restart to reload config.
Fix:
- Validate your JSON (missing braces/commas are common).
- Restart Claude Desktop fully.
- Ensure Node.js is installed and npx works (or use the Windows npx.cmd path).

Issue: You can connect, but tools fail unexpectedly

Root cause: Network restrictions, temporary service issues, or incorrect endpoint.
Fix:
- Confirm the MCP server health endpoint is reachable: GET /health on https://app.lemlist.com.
- Retry after a short delay.
- Check whether your environment blocks outbound HTTPS requests.

Knowledge Check (Quick Quiz)

Which authentication method are you using (OAuth or API key), and why is it the best fit for your environment?
Where do you configure MCP servers in your chosen client (Claude Desktop / Claude Code / Cursor)?
If using an API key, where is X-API-Key set in your configuration?
What’s your “safe first action” to verify connectivity before modifying campaigns?

Technical Reference (for advanced users)

Stack: Node.js (MeteorJS)
Protocol: MCP (JSON-RPC 2.0 over HTTP/POST)
Auth: OAuth (via mcp-remote) or API key in X-API-Key header
Validation: Zod schemas for inputs
Health check:GET /health

Find and use the lemlist API

Connect your email provider to lemlist

Set up DKIM, SPF, and DMARC

Set up Website Visitors on your website

Set up the lemlist MCP server in your LLM client (OAuth or API key)