Traackr API MCP Server

An MCP server for the Traackr API v1, built with FastMCP directly from the API's OpenAPI spec. Point any MCP client (Claude Code, Claude Desktop, Codex, …) at it and it runs on your machine with your own API key.

It is published to PyPI as traackr-api-mcp, so installing is a single uvx command — no clone, no build, no repository access.

Tools

Tool names, summaries, and descriptions are derived entirely from the OpenAPI spec (each operation's operationId / summary / description) — nothing is hardcoded, so new endpoints appear automatically as the spec evolves.

The table below reflects the spec at the time of writing — treat the live spec as the source of truth, since the server generates its tools from it at startup.

Prerequisites

• uv (provides uvx). Install with:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• A Traackr API key (provisioned by Traackr; sent as the X-Api-Key header).

uvx fetches and runs the published package in one step — there is nothing else to install.

Quick start

Pick your client. In every case, replace your-api-key-here with your key.

Claude Code

claude mcp add traackr \
  --env TRAACKR_API_KEY=your-api-key-here \
  -- uvx traackr-api-mcp

Claude Desktop

Edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "traackr": {
      "command": "uvx",
      "args": ["traackr-api-mcp"],
      "env": { "TRAACKR_API_KEY": "your-api-key-here" }
    }
  }
}

Restart Claude Desktop afterward.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.traackr]
command = "uvx"
args = ["traackr-api-mcp"]
env = { TRAACKR_API_KEY = "your-api-key-here" }

Any other MCP client

Use the same command and args:

command: uvx
args:    traackr-api-mcp
env:     TRAACKR_API_KEY=your-api-key-here

Versioning

uvx traackr-api-mcp runs the latest published release. To pin a specific version, append @<version>:

claude mcp add traackr \
  --env TRAACKR_API_KEY=your-api-key-here \
  -- uvx traackr-api-mcp@1.2.0

uvx caches builds, so if a new version has been published and you want it immediately, force a refresh:

uvx --refresh traackr-api-mcp

A full client restart after refreshing ensures the MCP server process is relaunched against the new build.

Configuration

All configuration is via environment variables (set them in your client's env block):

Staying in sync with the API

By default the server fetches the live OpenAPI spec from https://api.traackr.ai/api/openapi/v1 at startup and builds its tools from it — so new endpoints, fields, and description changes show up automatically with no package update. The package also ships a bundled copy (src/traackr_mcp/traackrapi.json) that is used only as an offline fallback if the live URL can't be reached.

If Traackr provides you with an alternate spec URL, point the server at it with TRAACKR_OPENAPI_URL.

Authentication

The Traackr API authenticates with an X-Api-Key header. OAuth is planned for a future release; when it lands, the static header on the httpx client in src/traackr_mcp/server.py can be swapped for an auth flow without changing the tool surface.

Troubleshooting

• ERROR: TRAACKR_API_KEY is not set — the server exits at startup rather than running and failing every call. Add the key to your client's env block (see Quick start) and restart the client.
• 403 {"message":"Forbidden"} (AWS ForbiddenException) — the request is fine, but the gateway is rejecting the key. Check the key is activated for the target environment. Reproduce outside MCP with:

  curl -i -H "X-Api-Key: $TRAACKR_API_KEY" "https://api.traackr.ai/api/v1/campaigns?limit=3"
  

• Output validation error — handled: the server runs with output-schema validation disabled, since the API returns null for optional fields the OpenAPI 3.0.1 spec marks non-nullable.