Metadata-Version: 2.4
Name: trakkr-mcp
Version: 0.3.0
Summary: MCP server for Trakkr — AI visibility monitoring for ChatGPT, Perplexity, Gemini, and more
Project-URL: Homepage, https://trakkr.ai
Project-URL: Documentation, https://trakkr.ai/learn/api/mcp
Project-URL: Repository, https://github.com/macklpgr/trakkr-mcp
Author-email: Trakkr <hello@trakkr.ai>
License-Expression: MIT
Keywords: ai-search,ai-visibility,brand-monitoring,mcp,trakkr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.0
Description-Content-Type: text/markdown

# trakkr-mcp

MCP server for [Trakkr](https://trakkr.ai) — AI visibility monitoring.

Connect your AI assistant (Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Windsurf, Zed, Cline, Continue, and any other MCP client) to Trakkr and query your brand's AI search visibility data conversationally.

## Quick Start

The fastest path is [uv](https://docs.astral.sh/uv/) — `uvx` auto-installs and runs the server with zero setup:

```bash
# One-time, if you don't have uv:
brew install uv

# Set your API key (get one at trakkr.ai/exports/api-keys):
export TRAKKR_API_KEY="sk_live_your_key_here"

# Optional, run the server directly to verify it works:
uvx trakkr-mcp
```

You usually don't run `uvx trakkr-mcp` yourself — your MCP client runs it for you based on the config below.

## Configuration

Pick the client you use. The full setup guide, including a live picker that updates the snippet per client, lives at [trakkr.ai/learn/api/mcp](https://trakkr.ai/learn/api/mcp).

### Claude Code (CLI)

Run once in any terminal:

```bash
claude mcp add trakkr \
  -e TRAKKR_API_KEY=sk_live_your_key_here \
  -- uvx trakkr-mcp
```

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "trakkr": {
      "command": "uvx",
      "args": ["trakkr-mcp"],
      "env": {
        "TRAKKR_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "trakkr": {
      "command": "uvx",
      "args": ["trakkr-mcp"],
      "env": {
        "TRAKKR_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### VS Code (Copilot Chat)

`.vscode/mcp.json` — uses the input-prompt pattern so the key never lands in source:

```json
{
  "servers": {
    "trakkr": {
      "type": "stdio",
      "command": "uvx",
      "args": ["trakkr-mcp"],
      "env": {
        "TRAKKR_API_KEY": "${input:trakkr-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "trakkr-api-key",
      "description": "Trakkr API Key",
      "password": true
    }
  ]
}
```

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.trakkr]
command = "uvx"
args = ["trakkr-mcp"]
env = { TRAKKR_API_KEY = "sk_live_your_key_here" }
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "trakkr": {
      "command": "uvx",
      "args": ["trakkr-mcp"],
      "env": {
        "TRAKKR_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### Zed

`~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "trakkr": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": ["trakkr-mcp"],
        "env": {
          "TRAKKR_API_KEY": "sk_live_your_key_here"
        }
      }
    }
  }
}
```

### Cline, Continue, or other MCP clients

Most clients accept the standard `mcpServers` JSON shown above for Cursor/Claude Desktop/Windsurf. Check your client's MCP documentation for the exact config file location, and see [trakkr.ai/learn/api/mcp](https://trakkr.ai/learn/api/mcp) for an up-to-date picker.

## Available Tools

### Core Data

| Tool | Description |
|------|-------------|
| `list_brands` | List all brands you're tracking. Returns brand IDs needed for other tools. |
| `get_visibility_scores` | Get AI visibility scores and trends over time. |
| `list_prompts` | List tracked search queries for a brand. |
| `manage_prompt` | Create, update, or delete a tracked prompt. |

### Visibility

| Tool | Description |
|------|-------------|
| `get_citations` | Citation URLs and trends. Views: list, history, queries, sources, feed, heatmap. |
| `get_rankings` | Competitive rankings in AI search results. |
| `get_model_breakdown` | Visibility by AI model (ChatGPT, Perplexity, Gemini, etc.). |
| `get_competitors` | Competitor analysis. Views: summary, arena, head-to-head, by-model, threats. |

### Intelligence

| Tool | Description |
|------|-------------|
| `get_opportunities` | Citation gaps where competitors appear but you don't. |
| `get_content_ideas` | AI-generated content ideas to improve visibility. |
| `get_perception` | How AI models describe and position the brand. Paid plan required. |
| `get_prism` | AI Pages analysis: positioning, strengths, weaknesses, opportunities. Paid plan required. |
| `get_narratives` | Narrative intelligence: tracked topics and storylines. Scale plan required. |

### Crawler

| Tool | Description |
|------|-------------|
| `get_crawler_overview` | Overview tab: hero stats, chart, setup state, top pages, and recent preview. |
| `get_crawler_live` | Live tab: activity, pages, or sessions with dashboard filters. |
| `get_crawler_pages` | Pages tab: pages, paths, or normalized bots. |
| `get_crawler_page_details` | Page drawer data: verdict, pipeline, health, traffic, diagnostics. |
| `get_crawler_path_details` | Path drawer data: verdict, pipeline, top pages, top bots, diagnostics. |
| `get_crawler_bot_details` | Bot drawer data: verdict, pipeline, top pages, top paths, diagnostics. |
| `get_crawler_access` | Access tab: findings, bot matrix, robots.txt, llms.txt, submit-to-search. |
| `preview_crawler_access_fix` | Preview an Access fix without applying it. |
| `send_crawler_verification_ping` | Send the verification ping shown in the dashboard. |
| `submit_crawler_to_search` | Submit crawler pages to AI search via IndexNow. |
| `get_crawler_submit_status` | Read submit-to-search status and summary. |
| `get_crawler_analytics` | Deprecated compatibility alias for the new crawler tools. |

### Audit & Recommendations

Read-only access to Trakkr's unified recommendation queue and site-audit data. These tools never trigger analysis or generation — they surface data the dashboard has already produced. Ideal for running an AI-search technical audit conversationally.

| Tool | Description |
|------|-------------|
| `get_actions` | List recommended actions from the unified queue (audit, crawler, prompts, citations, etc.). Filter by source, category, action_type, lens, or quick_win. |
| `get_action_stats` | Aggregate counts by status, category, action_type, and source. |
| `list_audits` | List site audits for a brand (overall_score, issue counts, detected CMS). |
| `get_audit_findings` | Audit issues + flagged pages for the latest (or specified) audit. Includes has_llms_txt / ai_crawler_blocked / has_sitemap rollups. |
| `list_page_analyses` | List recent cached deep page analyses for a brand. |
| `get_page_analysis` | Cached deep analysis for one URL — AI diagnosis, citation verdict, failed checks, ready-to-paste schema, entities, bot visibility. |

### Actions

| Tool | Description |
|------|-------------|
| `run_diagnosis` | Diagnose a search query across AI models in real-time. |
| `get_diagnosis_result` | Get diagnosis results, history, or usage quota. |
| `generate_report` | Generate an AI visibility report (executive, weekly, or full). |
| `get_reports` | List or retrieve generated reports. |
| `export_data` | Export data as JSON or CSV. |

## Example Conversations

Once connected, you can ask your AI assistant things like:

- "How is my brand doing in AI search this month?"
- "Which competitors are gaining ground in ChatGPT?"
- "What content opportunities am I missing?"
- "Show me which pages get cited most by Perplexity"
- "Run a diagnosis on 'best project management tools'"
- "What does my visibility trend look like over the last 90 days?"
- "Show crawler overview for Nike"
- "What changed in Live this week?"
- "Preview crawler access fixes"
- "Send a verification ping"
- "Run a full AI search technical audit of my brand"
- "What are my top open actions right now?"
- "Show me every critical/high issue from the latest audit, and the worst-scoring pages"
- "What's the deep page analysis say about /pricing?"

## Requirements

- Python 3.10+
- A Trakkr account with an API key ([get one here](https://trakkr.ai/exports/api-keys))

## Documentation

Full API documentation: [trakkr.ai/learn/api](https://trakkr.ai/learn/api)

MCP setup guide: [trakkr.ai/learn/api/mcp](https://trakkr.ai/learn/api/mcp)

## License

MIT
