leadmaps

Connect AI agents to Leadmaps — 13.2M European local-business listings — in one command. No install needed:

$ npx leadmaps connect --agent claude
✓ 13,233,049 listings reachable
✓ Registered with Claude Code (claude mcp add --transport http --scope user)

Try this first prompt:
  "Find 150 real-estate agencies in Lille rated ≥ 4.4 with a website, export to CSV."

Zero runtime dependencies, Node >= 18.

Commands

leadmaps connect [--agent claude|cursor|windsurf|n8n] [--key lm_...]

1. Resolves your API key: --key flag → LEADMAPS_API_KEY env var → interactive prompt.
2. Validates it live before touching anything: an unauthenticated GET https://api.leadmaps.io/healthz, then a free authenticated GET /v1/places/count (counting never costs credits). An invalid key exits with a clear error and writes nothing.
3. Wires the Leadmaps MCP server (https://mcp.leadmaps.io/mcp, streamable HTTP, Authorization: Bearer header) into the chosen agent.

leadmaps status [--key lm_...]

Health of api.leadmaps.io and mcp.leadmaps.io, the live listing total, and — for lm_live_ keys — your plan, credit usage, overage and spending cap (from the free GET /v1/usage endpoint).

What it writes, where

| Agent | Target | Notes | | --- | --- | --- | | claude | claude mcp add --transport http --scope user leadmaps … when the claude CLI is on your PATH; otherwise merges into ~/.claude.json | User scope: available in every Claude Code session | | cursor | ~/.cursor/mcp.json | Restart Cursor; the six leadmaps tools appear in the MCP panel | | windsurf | ~/.codeium/windsurf/mcp_config.json | Uses Windsurf's serverUrl syntax | | n8n | Nothing — prints a ready-to-paste recipe | MCP Client node and HTTP Request node variants, key filled in |

All three config locations live under your home directory on macOS, Linux and Windows (os.homedir() + the same relative path), so the CLI is platform-agnostic. On Windows the Claude wiring always goes through ~/.claude.json directly — the exact file claude mcp add --scope user manages.

Config files are handled with care:

• Read–modify–write: every existing key and every other MCP server in the file is preserved; only mcpServers.leadmaps is added or replaced.
• Backup first: before modifying an existing file, an exact copy is saved next to it as <file>.bak.
• Never destroys what it cannot parse: if the target file is not valid JSON, the CLI aborts with a message pointing at the file and leaves it untouched (the .bak copy is still written, so you have a spare).

API keys

Create keys at app.leadmaps.io/keys:

• lm_test_… — free sandbox key: ~5,000 real listings, 0 credits, no card. Perfect for trying the MCP tools.
• lm_live_… — production key for the full 13.2M dataset.

The key can be supplied three ways (first match wins): --key lm_…, the LEADMAPS_API_KEY environment variable, or the interactive prompt. The CLI never stores the key anywhere except the agent config you asked it to write. If a key leaks, revoke it at app.leadmaps.io/keys and re-run leadmaps connect.

Uninstall

The CLI itself leaves nothing behind (run it with npx). To disconnect an agent:

• Claude Code: claude mcp remove leadmaps -s user (or delete the leadmaps entry from mcpServers in ~/.claude.json).
• Cursor: remove the leadmaps entry from ~/.cursor/mcp.json.
• Windsurf: remove the leadmaps entry from ~/.codeium/windsurf/mcp_config.json.
• Then revoke the key at app.leadmaps.io/keys if you no longer use it.

Advanced

LEADMAPS_API_URL and LEADMAPS_MCP_URL override the default endpoints (staging/self-hosted setups).

Development

$ npm test   # node --test — config-merge logic, key validation, stubbed API calls; no network

MIT © Leadmaps