Keitaro Server

MCP server for Keitaro Tracker Admin API. Provides 37 tools for campaign management, traffic analytics, reports, and raw click/conversion data — accessible from Claude Code, Cursor, and other MCP-compatible AI agents.

Quick Start

Prerequisites

• Python >= 3.11
• uv (install guide)
• curl (pre-installed on most systems)
• Keitaro API key (see How to Get API Key below)

Step 1: Clone the repository

git clone https://github.com/KeitaroManager/keitaro-mcp.git

Choose where to clone. It can be anywhere — your home directory, a tools folder, etc:

# Example locations:
git clone https://github.com/KeitaroManager/keitaro-mcp.git ~/keitaro-mcp
git clone https://github.com/KeitaroManager/keitaro-mcp.git ~/tools/keitaro-mcp
git clone https://github.com/KeitaroManager/keitaro-mcp.git /opt/keitaro-mcp

Step 2: Install the MCP server

Pick ONE of the two scopes below. Replace the placeholder values with your real tracker URL and API key.

Option A — Project scope (available only when working inside a specific project directory):

cd /path/to/your/project

claude mcp add keitaro -s project \
  -e KEITARO_URL=https://your-tracker.example.com \
  -e KEITARO_API_KEY=your-api-key-here \
  -- uv --directory /absolute/path/to/keitaro-mcp run python -m keitaro_mcp

Option B — User scope (available in all your projects, globally):

claude mcp add keitaro -s user \
  -e KEITARO_URL=https://your-tracker.example.com \
  -e KEITARO_API_KEY=your-api-key-here \
  -- uv --directory /absolute/path/to/keitaro-mcp run python -m keitaro_mcp

Step 3: Done

Restart Claude Code. The keitaro_* tools are now available. Try:

You: "List my Keitaro campaigns"
You: "Show ROI by campaign for last 7 days"
You: "Create a campaign named Test"

Full Example (copy-paste ready)

# 1. Clone
git clone https://github.com/KeitaroManager/keitaro-mcp.git ~/keitaro-mcp

# 2. Install (project scope — run this inside your project directory)
claude mcp add keitaro -s project \
  -e KEITARO_URL=https://tracker.mycompany.com \
  -e KEITARO_API_KEY=abc123def456 \
  -- uv --directory ~/keitaro-mcp run python -m keitaro_mcp

# 3. Restart Claude Code and use it

How to Get API Key

1. Log into your Keitaro tracker admin panel
2. Go to Maintenance → Users (or click your account icon → Account → API keys)
3. Click Create API key
4. Copy the key — it cannot be viewed again after creation

The API key requires admin or expert-level permissions.

Updating

When a new version is released, pull the latest code:

cd /path/to/keitaro-mcp
git pull

That's it. The next time Claude Code starts, it will use the updated version automatically. No reinstall needed — uv reads the source directly.

Uninstalling

# Remove from project scope
claude mcp remove keitaro -s project

# Or remove from user scope
claude mcp remove keitaro -s user

Multiple Keitaro Instances

If you have more than one Keitaro tracker (e.g. production + staging), create a JSON config file:

[
  {
    "name": "production",
    "url": "https://tracker.example.com",
    "api_key": "prod-api-key",
    "description": "Production tracker"
  },
  {
    "name": "staging",
    "url": "https://staging.example.com",
    "api_key": "staging-api-key",
    "description": "Staging tracker"
  }
]

Save it (e.g. ~/keitaro-instances.json), then install with:

claude mcp add keitaro -s project \
  -e KEITARO_CONFIG_FILE=/absolute/path/to/keitaro-instances.json \
  -- uv --directory /absolute/path/to/keitaro-mcp run python -m keitaro_mcp

When multiple instances are configured, tools accept an optional instance parameter. If only one instance exists, it is selected automatically.

Connecting to Cursor

Add to Cursor settings (Settings → MCP Servers → Add):

{
  "keitaro": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/keitaro-mcp", "run", "python", "-m", "keitaro_mcp"],
    "env": {
      "KEITARO_URL": "https://your-tracker.example.com",
      "KEITARO_API_KEY": "your-api-key"
    }
  }
}

What It Does

37 Tools by Category

Category	Tools	Operations
Campaigns	7	List, get, create, update, archive, clone, enable/disable
Streams (Flows)	6	List, get, create, update, delete, enable/disable
Offers	5	List, get, create, update, archive
Landing Pages	5	List, get, create, update, archive
Traffic Sources	3	List, get, create
Affiliate Networks	3	List, get, create
Domains	3	List, get, check DNS/SSL
Groups	1	List by type
Reports	1	Build aggregated report (dimensions, measures, filters, sort)
Clicks	1	Query raw click log with pagination
Conversions	1	Query raw conversion log with pagination
Platform	1	List configured instances

Analytics: Report Builder

The keitaro_build_report tool is the primary analytics interface:

• 30+ metrics: clicks, conversions, revenue, profit, ROI, CR, CPC, CPA, EPC, cost, leads, sales...
• 50+ dimensions: campaign, offer, landing, country, day, hour, device, browser, OS, sub_id_1..30...
• 20+ filter operators: EQUALS, GREATER_THAN, CONTAINS, IN_LIST, BETWEEN, MATCH_REGEXP...
• Date ranges: any from/to with timezone support

Example:

User: "Show me ROI by campaign for the last 7 days, sorted by profit"
→ keitaro_build_report(date_from="2026-03-17", date_to="2026-03-24",
    dimensions=["campaign"], measures=["clicks", "conversions", "revenue", "profit", "roi"],
    sort=[{name: "profit", order: "DESC"}])

Raw Data: Clicks & Conversions

Query individual click and conversion records with column selection, filtering, and pagination. Useful for debugging traffic quality, checking specific sub_ids, or investigating conversions.

Full Tool List

Read Tools (safe, no side effects) — 19 tools

Tool	Description
keitaro_list_instances	List configured tracker instances
keitaro_list_campaigns	List campaigns (supports limit/offset)
keitaro_get_campaign	Get campaign by ID
keitaro_list_streams	List streams for a campaign
keitaro_get_stream	Get stream by ID
keitaro_list_offers	List all offers
keitaro_get_offer	Get offer by ID
keitaro_list_landing_pages	List all landing pages
keitaro_get_landing_page	Get landing page by ID
keitaro_list_traffic_sources	List all traffic sources
keitaro_get_traffic_source	Get traffic source by ID
keitaro_list_affiliate_networks	List all affiliate networks
keitaro_get_affiliate_network	Get affiliate network by ID
keitaro_list_domains	List all domains
keitaro_get_domain	Get domain by ID
keitaro_list_groups	List groups by type
keitaro_build_report	Build aggregated analytics report
keitaro_get_clicks	Query raw click records
keitaro_get_conversions	Query raw conversion records

Write Tools (create, update, modify) — 18 tools

Tool	Description
keitaro_create_campaign	Create a new campaign
keitaro_update_campaign	Update campaign fields
keitaro_delete_campaign	Archive campaign (soft delete, reversible)
keitaro_clone_campaign	Duplicate campaign with streams
keitaro_toggle_campaign	Enable or disable campaign
keitaro_create_offer	Create a new offer
keitaro_update_offer	Update offer fields
keitaro_delete_offer	Archive offer
keitaro_create_stream	Create stream in a campaign
keitaro_update_stream	Update stream fields
keitaro_delete_stream	Delete stream
keitaro_toggle_stream	Enable or disable stream
keitaro_create_landing_page	Create landing page
keitaro_update_landing_page	Update landing page
keitaro_delete_landing_page	Archive landing page
keitaro_create_traffic_source	Create traffic source
keitaro_create_affiliate_network	Create affiliate network
keitaro_check_domain	Check domain DNS/SSL status (triggers active probe)

Architecture

keitaro-mcp/
├── pyproject.toml                  # Package config, dependencies
├── README.md                       # This file
├── LICENSE                         # MIT
├── .env.example                    # Configuration template
├── keitaro-instances.example.json  # Multi-instance config template
└── src/keitaro_mcp/
    ├── __init__.py                 # Entry point
    ├── __main__.py                 # python -m keitaro_mcp
    ├── server.py                   # MCP Server — 37 tools, match/case routing
    ├── client.py                   # HTTP client (curl subprocess)
    ├── registry.py                 # Multi-instance support
    └── errors.py                   # Error types

Why curl instead of requests/httpx?

Keitaro trackers are typically behind Cloudflare. Python HTTP libraries (urllib, httpx, requests) use TLS fingerprints that Cloudflare identifies and blocks with 403 Forbidden. curl uses a different TLS stack that passes through. This is a deliberate architectural choice.

Design Principles

• Low-level MCP Server with match/case routing — scales well for 37+ tools
• Zero Python dependencies beyond mcp>=1.0.0 — uses system curl for HTTP
• Multi-instance — one server can connect to multiple Keitaro trackers
• Structured errors — all errors return JSON {"error": "..."}, server never crashes
• AI-optimized — every tool has detailed description with field lists, enums, and usage hints

Keitaro API Reference

This server wraps the Keitaro Admin API v1. Full OpenAPI spec covers 119 endpoints. This MCP server covers the most commonly used operations.

Key Keitaro concepts:

• Campaign → has Streams (flows) → each stream routes to Landings and Offers
• Offers belong to Affiliate Networks (for postback tracking)
• Traffic Sources define where clicks come from (Facebook, Google, etc.)
• Domains are tracker URLs used for campaign links
• Groups organize campaigns, offers, and landings into categories

Contributing

1. Clone the repo
2. Install dev dependencies: uv pip install -e ".[dev]" (or pip install -e ".[dev]")
3. Make changes in src/keitaro_mcp/
4. Test: python -c "from keitaro_mcp.server import TOOLS; print(f'{len(TOOLS)} tools OK')"
5. Submit a PR

To add a new tool:

1. Add the API method to client.py
2. Add the Tool() definition to TOOLS list in server.py
3. Add the match case handler in call_tool() in server.py

License

MIT