io.github.leadpipe-com/leadpipe

Leadpipe MCP

Official MCP server for Leadpipe intent and data APIs.

Use this server to give agents direct access to:

• topic discovery
• website topic analysis
• audience preview and ad hoc query
• saved audience management
• audience status, results, runs, stats, and exports
• visitor data lookup
• tracking pixel management
• account health and credit status

What This Is

Leadpipe MCP wraps the public Leadpipe intent and data APIs in a local MCP server that agents can use over stdio.

This server is API-key authenticated by default so the full audience workflow, visitor data access, and pixel management workflows are available to agents.

Use With Claude, Cursor, and Codex

Most users do not need to clone this repo or build from source. The published package is:

npx -y @leadpipe/mcp

You will need:

export LEADPIPE_API_KEY=sk_...

Optional advanced override:

export LEADPIPE_BASE_URL=https://api.aws53.cloud

LEADPIPE_BASE_URL only needs to change if you are pointing at a non-default environment.

Claude Desktop

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "leadpipe": {
      "command": "npx",
      "args": ["-y", "@leadpipe/mcp"],
      "env": {
        "LEADPIPE_API_KEY": "sk_..."
      }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "leadpipe": {
      "command": "npx",
      "args": ["-y", "@leadpipe/mcp"],
      "env": {
        "LEADPIPE_API_KEY": "sk_..."
      }
    }
  }
}

Codex

Add the server with the Codex CLI:

codex mcp add leadpipe --env LEADPIPE_API_KEY=sk_... -- npx -y @leadpipe/mcp

Then confirm it is configured:

codex mcp list

Quick Start

If you just want to verify the package runs:

npx -y @leadpipe/mcp

Run From Source

For local development or repo hacking:

npm install
npm run build
node dist/index.js

For iterative local development:

npm run dev

Local source build MCP config:

{
  "mcpServers": {
    "leadpipe": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "LEADPIPE_API_KEY": "sk_..."
      }
    }
  }
}

Tool Surface

Topic Discovery

• list_topics
• get_topic_facets
• search_topics
• get_topic_trend
• compare_topics
• get_topic_movers
• analyze_website_topics

Audience Builder

• get_audience_filters
• preview_audience
• query_audience
• list_audiences
• get_audience
• create_audience
• update_audience
• delete_audience

Audience Results

• get_audience_status
• get_audience_results
• list_audience_runs
• get_audience_stats
• export_audience

Visitor Data

• query_visitor_data

Pixels

• list_pixels
• create_pixel
• update_pixel

Account

• get_account_status

Prompts

• discover-audience-topics
• operate-saved-audience
• investigate-visitor-data

Prompt Examples

See examples/prompt-examples.md for copy-paste prompts that work well with this MCP server.

Good starting prompts:

• "Find 5-10 B2B topics for cloud cost optimization software, compare their recent trends, and preview an audience."
• "Create a saved audience for these topics, activate it, wait until it is ready, and then summarize the first page of results."
• "Check the status of audience <audience-id>. If it is ready, export it and give me the download URL."
• "Investigate visitor activity for example.com over the last 30 days and tell me whether our tracking setup looks healthy."
• "List our pixels, find any paused ones, and explain what needs attention."

Agent Playbooks

For more structured operational flows, see:

• Audience Research Playbook
• Visitor Diagnostics Playbook

Resources

• leadpipe://docs/auth
• leadpipe://docs/workflows
• leadpipe://docs/data-api

Typical Agent Workflow

1. Search or analyze topics
2. Preview audience size
3. Create or update a saved audience
4. Check status until the audience is ready
5. Fetch results or export CSV

Typical Data Workflow

1. Check get_account_status
2. Query visitor activity with query_visitor_data
3. Inspect or create pixels with list_pixels / create_pixel
4. Pause or reactivate tracking with update_pixel

Development

npm run typecheck
npm run build

License

MIT