Metadata-Version: 2.4
Name: trakkr-mcp
Version: 0.5.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. |

### Research

Read access to the full prompt research analytics — the same payload that powers the in-app `/research` page. Topic snapshots can be triggered too, gated by the brand's monthly snapshot credits (Trial 1, Growth 3, Scale 10). Full prompt research runs are not exposed — they run daily on a schedule.

| Tool | Description |
|------|-------------|
| `get_latest_research` | Most recent completed run with the full analytics payload. Canonical "what does my latest research show" lookup. |
| `get_research_runs` | List runs newest-first with visibility, mention rate, top competitors, and snapshot topic where applicable. |
| `get_research_run` | Full payload for one run: visibility, position distribution, competitor share, intent and focus breakdowns, best/missed prompts, per-prompt results. |
| `get_research_credits` | Topic snapshot credit usage for the current month. |
| `run_research_snapshot` | Trigger a topic snapshot (~75 focused prompts). Async, 3-5 min; consumes one monthly credit. |

### 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. |

### Reddit

| Tool | Description |
|------|-------------|
| `get_reddit` | Reddit monitoring data. Views: overview, feed, opportunities, thread, subreddits, triggers, analytics. |
| `manage_reddit_subreddit` | Add or remove monitored subreddits. Add uses the public API `subreddit_name` body field. |
| `manage_reddit_trigger` | Add or remove keyword triggers that drive Reddit scanning. |
| `manage_reddit_opportunity` | Dismiss an opportunity or mark it responded. |
| `scan_reddit` | Queue an on-demand Reddit scan. |

### Workflows

| Tool | Description |
|------|-------------|
| `get_workflows` | Read workflow definitions, runs, run details, or templates. |
| `manage_workflow` | Pause, resume, soft-delete, or clone from a template. Delete maps to `PATCH /workflows/{id}` with `status=deleted`. |

### Activity

| Tool | Description |
|------|-------------|
| `get_notifications` | Read notifications by `event_type`, unread state, and lookback window. |
| `mark_notifications_read` | Mark specific notifications read or use `mark_all=true` for the brand. |
| `manage_webhook` | List, inspect, create, delete, or test webhooks. Create uses `signing_secret` and underscore event names such as `visibility_changed`. |

### Content

| Tool | Description |
|------|-------------|
| `get_knowledge` | Read knowledge sources or aggregate stats. Views: sources, stats. |
| `get_articles` | Read articles. Views: list, detail. Status filters: draft, review, ready, published. |
| `get_writing_style` | Read writing style profile or source samples. |

### Agency

| Tool | Description |
|------|-------------|
| `list_brand_groups` | List accessible agency brand groups with member brands. |
| `compare_brands` | Compare 2-10 brands across visibility, citations, and actions. |
| `get_portfolio_actions` | Highest-impact open actions across accessible brands, optionally filtered by `group_id` or `quick_win`. |

## 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?"
- "Summarize my latest research run — visibility, top competitors, and missed prompts"
- "Run a topic snapshot on 'enterprise pricing pages' and tell me when it's done"
- "What Reddit threads should I jump into this week?"
- "List my active workflows and what fired in the last seven days"
- "Show unread visibility_drop notifications and mark them all as read"
- "Wire a webhook to https://example.com/hook for visibility_changed and citation_gained"
- "Compare these brands on visibility, citations, and actions"

## 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
