> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.leadscraper.eu/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connect Leadscraper to your AI via MCP

You can connect Leadscraper directly to your AI client — for example **Claude** (Desktop & Web), **ChatGPT** (Custom GPTs), **Cursor**, or your own agent. Then you can start lead searches, check their status, pull leads, and check your credit balance without ever opening Leadscraper — just by talking to your AI.

This is powered by **MCP** (Model Context Protocol) — an open standard that lets AI clients talk securely to external tools. Leadscraper runs its own MCP server for this.

## What you get

- **Research straight from your AI workflow.** "Find me 10 carpentry shops in Bavaria" — and your AI kicks off the run in Leadscraper and brings back the results.
- **No tool-switching.** Search, status, and leads all happen where you already work.
- **Your account, your rules.** Credits are billed as usual (1 credit per delivered lead).

## Requirements

- A Leadscraper account.
- An MCP-capable AI client (e.g. Claude.ai, Claude Desktop, ChatGPT, or Cursor).

## Path 1 – Connect Claude.ai (web) via OAuth (fastest)

For Claude.ai in your browser you don't need a token at all. The whole flow takes under a minute.

### Step 1 – Open the MCP card in your Integrations settings

1. Log in at my.leadscraper.de.
2. Click your avatar (top-right) → **Account settings** → **Integrations**.
3. On the **Leadscraper as MCP server** card, click **Connect to Claude**.

![The Integrations card lets you start the OAuth flow — no token needed for Claude.ai.](https://public.deimann.io/img/help-ls/mcp_connect_step-01.png)

### Step 2 – Copy the server URL and add the connector in Claude

A modal appears showing your MCP server URL (`https://mcp.leadscraper.eu/mcp`) with a one-click Copy button. Then:

1. Click **Open Claude connectors ↗** (or open Claude → Settings → Connectors → Add custom connector).
2. Paste the server URL and continue.
3. Claude redirects you to a Leadscraper **Allow** consent screen — click **Allow**.

> Already logged in to Leadscraper? The consent screen is a single click — no separate password needed. If Claude doesn't redirect you back automatically, just switch back to your Claude tab; the connector will already show as connected.

### Step 3 – Verify the connection

Ask Claude something like:

- "List my leadscraper profiles"
- "What's my leadscraper credit balance?"

If Claude returns your real account data, the connection is fully live.

## Path 2 – Manual token (Claude Desktop, Cursor, your own agent)

Use this path if you prefer a bearer token, or for clients that don't support OAuth — Claude Desktop, Cursor, or custom agent SDKs.

1. On the Integrations page, click **Generate token** (next to Connect to Claude).
2. In the **Connect an AI client** modal, enter a name (e.g. "Claude Desktop") and click **Generate token**.

![The "Connect an AI client" modal lets you generate a named token — it's shown only once.](https://public.deimann.io/img/help-ls/mcp_connect_step-02.png)

3. **Copy the token immediately and store it safely.** For security reasons it's shown only **once**.
4. Add it to your MCP client config as a bearer token along with the server URL.

```json
{
  "mcpServers": {
    "leadscraper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.leadscraper.eu/mcp",
        "--header",
        "Authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}
```

Restart your client afterwards and check that the tools icon appears — that means the connection is active.

**Server URL:** `https://mcp.leadscraper.eu/mcp`

> **Token validity:** Manual tokens expire automatically after **90 days**. You'll see a **Revoke** link next to each token on the Integrations page, in case you want to pull it early — say a token is no longer needed or may be compromised.

## What you can do via the AI

Six tools are currently available:

| Tool | What it does |
|---|---|
| **list_profiles** | Lists your saved lead-search profiles. |
| **create_profile** | Creates a new lead-search profile. |
| **create_lead_search** | Starts a new lead search on an existing profile. |
| **get_search_status** | Checks the status of a running search. |
| **list_leads** | Lists delivered leads for a profile — the same data you see in the product. |
| **get_credit_balance** | Returns your current credit balance. |

In practice, you just talk to your AI — e.g. *"Start a search for electricians in Hamburg and show me the results as soon as they're in."* The AI calls the right tools behind the scenes.

> **Currently read + search only:** actions that spend extra credits on contact lookups or push data to a CRM (e.g. connecting to Pipedrive/HubSpot, drafting outreach emails) are intentionally held back until a spend-confirmation step ships. These will be enabled without needing you to reconnect.

## Credits & security

- **Credits:** a search spends credits as usual — one credit per delivered lead. Whatever your AI does, each token/connection has protective limits so nothing runs away unintended.
- **Access:** the connection accesses only **your** account, is stored encrypted, and can be revoked at any time.
- **Validity:** OAuth connections (Claude.ai) last ~30 days and are refreshed automatically by Claude. Manual tokens expire after 90 days.
- **Errors:** if a tool call fails, Claude shows a specific reason (e.g. insufficient credits, invalid request) rather than a generic failure message.
- **Your normal login is unaffected** — the MCP connection runs entirely in parallel.

## Troubleshooting

**"Add custom connector" doesn't accept a token field?**
That's expected — Claude's custom connector flow uses OAuth only. Just paste the server URL and authenticate via the Allow screen, not a token.

**Some tools are missing compared to before?**
If you previously connected via a token-based setup, you may see only the six read-only/search tools listed above. Credit-spending and CRM-push tools are intentionally disabled until a spend-confirmation step ships.

**Connector disconnects after a day?**
This was a known issue with short-lived tokens and has been fixed — OAuth connections now persist for ~30 days. If you're still seeing daily disconnects, please reach out via the in-app chat.

## FAQ

**Do I need to know how to code?**
Not for Claude.ai — one click on "Connect to Claude" and no token is needed. For other clients, you generate a token and add it with the server URL to your client config.

**What if I lost my token?**
No problem: revoke the old one and create a new one. For security reasons an existing token can't be shown again.

**Does connecting itself use credits?**
No. Only an actually started search or contact lookup costs credits — same as in the product.

**Which AI clients are supported?**
Claude (Desktop & Web), ChatGPT (Custom GPTs), Cursor, and any other MCP-capable client, including your own agent SDKs.

**Can I still use Leadscraper normally in the browser?**
Yes, without limitation. MCP is an additional way in, not a replacement.