Metadata-Version: 2.4
Name: trakkr-mcp
Version: 0.10.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: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<2,>=1.26
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 MCP connect token from Settings > Developer:
export TRAKKR_API_KEY="mcp_connect_your_token_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.
Scale users with legacy `sk_live_` REST keys can still use those keys for direct local mode, but new setups should use the MCP connect token.

## 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=mcp_connect_your_token_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": "mcp_connect_your_token_here"
      }
    }
  }
}
```

### Cursor

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

```json
{
  "mcpServers": {
    "trakkr": {
      "command": "uvx",
      "args": ["trakkr-mcp"],
      "env": {
        "TRAKKR_API_KEY": "mcp_connect_your_token_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-connect-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "trakkr-connect-token",
      "description": "Trakkr MCP connect token",
      "password": true
    }
  ]
}
```

### Codex CLI

`~/.codex/config.toml`:

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

### Windsurf

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

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

### Zed

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

```json
{
  "context_servers": {
    "trakkr": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": ["trakkr-mcp"],
        "env": {
          "TRAKKR_API_KEY": "mcp_connect_your_token_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

The heaviest read tools (`get_citations`, `get_competitors`, `get_reports`, `get_research_run`) take a `response_format` argument: `concise` (the default) caps long lists and drops verbose dumps so the result never swamps the model's context, while `detailed` returns the full payload. Either way a size guard holds every response under the context ceiling and, when it trims, tells you how to fetch the rest (page with `offset`, narrow the window, or read the matching `trakkr://` resource).

### 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. |
| `suggest_prompts` | Suggest fresh prompts to track, grounded in the brand's own profile and deduped against what it already tracks. |
| `update_brand_aliases` | Update the brand's aliases (alternate names folded into its visibility). Add, remove, or set. |

### 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 5, Scale 5, per active brand). 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 (50 focused prompts). Async, 3-5 min; consumes one monthly credit (5/mo per active brand). |

### 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_detail` | Drawer data for one page, path, or bot (`kind` + `entity_id`): verdict, pipeline, health, traffic, 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. |

### 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_changes` | What moved for a brand since a timestamp: visibility, citations, competitors, rank, crawler signals, opportunities, reports. Returns a `latest_seen` cursor to pass back as `since` next time. A daily watch digest, not a live feed. |
| `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`. |

## Resources

Resources let a client pull Trakkr context into a chat with no tool call (for example `@trakkr://brand/<id>/briefing` in clients that support resources). Each one is a small, read-only, bounded view, so reading it never triggers analysis or compute.

### Your brand (paste-ready briefings)

Markdown you can @-attach to any chat (writing a page, briefing an agency, steering another AI). Each reads like a brief, not a payload, and is summary-first and bounded.

| Resource | Description |
|----------|-------------|
| `trakkr://brand` | The index of your brands and their IDs, each linked to the briefings below. Start here to find a brand ID. |
| `trakkr://brand/{brand_id}/brand-book` | The star: paste-ready context so any AI describes the brand right. What it is, how AI frames it today, what to set straight, and the proof. |
| `trakkr://brand/{brand_id}/snapshot` | Latest AI visibility: the headline scores, a by-model table, and the prompts where you win and where you lose. |
| `trakkr://brand/{brand_id}/citation-gaps` | Prompts where AI cites a rival but not you, ranked, with who gets cited and what to publish to win them. |
| `trakkr://brand/{brand_id}/prompts` | The AI-search questions Trakkr is tracking for this brand, active and paused. |

### Your brand (live state, JSON)

Machine-shaped views for programmatic reads.

| Resource | Description |
|----------|-------------|
| `trakkr://brands` | The brands you can access, with the IDs that fill the per-brand templates below. |
| `trakkr://brand/{brand_id}/briefing` | Headline state: current visibility and trend plus the open-action snapshot. |
| `trakkr://brand/{brand_id}/actions` | The brand's top open actions, most impactful first. |
| `trakkr://brand/{brand_id}/changes` | What moved in the last week. The same digest as `get_changes`. |
| `trakkr://brand/{brand_id}/latest-report` | The most recent generated report (headline metrics and metadata). |

### Data & Research

Every rival shows you your own numbers. These resources expose Trakkr's public research on what actually moves the needle in AI search: the evidence behind getting cited. Each one reads as a sharp analyst briefing (a lead number, a tight table, a short "what to do"), fetched live from Trakkr's public `/data` studies and cached, so the figures stay current and the package never ships stale numbers. The data is public/CC, so attribution is welcome.

| Resource | Description |
|----------|-------------|
| `trakkr://data` | Index of the research briefings below, with a one-line hook for each. |
| `trakkr://data/what-gets-cited` | Which page types earn AI citations (blogs win, product and help pages lose), and owned vs third-party. |
| `trakkr://data/crawler-personalities` | What each AI bot actually fetches and reads, and how aggressively it crawls. |
| `trakkr://data/llms-txt-truth` | The honest null result: llms.txt shows no detectable citation lift. |
| `trakkr://data/schema-advantage` | How strongly structured data correlates with getting cited by AI. |
| `trakkr://data/citation-decay` | How fast AI citations fade: most last a single day. |
| `trakkr://data/model-divergence` | Where AI models disagree on who to recommend (they agree under half the time). |
| `trakkr://data/playbook` | The synthesis: the rules for getting cited in AI search, with links to the evidence. |

## Workflows (Prompts)

Prompts are server-provided slash commands. The moment Trakkr is connected they appear in your client's prompt menu (`/weekly-review`, `/citation-gap-plan`, and so on). Each one is a parameterised playbook: it chains the right tools and the `trakkr://data` research in the right order and shapes the result into a finished, scannable briefing, most important first. Arguments are optional. Leave a brand out and the workflow resolves it for you.

| Prompt | What you get |
|--------|--------------|
| `weekly-review` | Your Monday AI-search brief. Visibility and trend, who is gaining, the biggest citation gaps, and the easy wins, as five tight bullets. Args: `brand`, `period` (default `7d`). |
| `competitor-teardown` | Where a rival beats you, where you beat them, and three moves to close the gap. Args: `brand`, `competitor`. |
| `citation-gap-plan` | The prompts you are losing, cross-referenced with the research on what actually gets cited, ending in a ranked plan of what to publish. Args: `brand`. |
| `content-brief` | A citation-optimised outline plus the on-page schema to include for one piece, ready to hand to a writing tool. Args: `brand`, `topic`. |
| `setup-tracking` | Onboarding in one conversation: confirm the brand, set its market, then propose a starter set of prompts to track and create them on your say-so. Args: `domain`. |
| `trakkr-watch` | A watch playbook. Pulls the latest changes for a brand, summarizes what moved in plain language, and offers next steps. On repeat checks, pass the last `latest_seen` cursor so you only see what is new. Args: `brand_id`, `since`. |

## 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"
- "/weekly-review Nike" for a five-bullet Monday brief, or "/citation-gap-plan" for a ranked plan of what to publish
- "/competitor-teardown Nike Adidas" to see exactly where a rival is winning and the three moves to close it
- "Keep an eye on Nike and tell me if anything moves" (uses the `trakkr-watch` prompt)
- "What changed for my brand since yesterday?"
- "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"
- "Using Trakkr's research, what page types actually get cited in AI search?" (reads `trakkr://data/what-gets-cited`)
- "Does llms.txt help me get cited?" (reads `trakkr://data/llms-txt-truth`)
- "Give me the AI-search playbook for getting cited" (reads `trakkr://data/playbook`)

## Requirements

- Python 3.10+
- A paid Trakkr account with an MCP connect token from Settings > Developer

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