Metadata-Version: 2.5
Name: traackr-api-mcp
Version: 0.4.0
Summary: MCP server for the Traackr API v1, generated from its OpenAPI spec.
Project-URL: Homepage, https://www.traackr.ai
Project-URL: Documentation, https://api.traackr.ai/api/openapi/v1
Author: Traackr
License-Expression: MIT
License-File: LICENSE
Keywords: fastmcp,influencer-marketing,mcp,model-context-protocol,openapi,traackr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.4.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.27.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: starlette>=1.3.1
Description-Content-Type: text/markdown

# Traackr API MCP Server

An [MCP](https://modelcontextprotocol.io) server for the **Traackr API v1**, built
with [FastMCP](https://gofastmcp.com) directly from the API's OpenAPI spec. Use it
either way — the tools are the same:

- **Hosted** (pilot) at `https://api.mcp.traackr.ai/mcp`: nothing to install; your MCP
  client sends your API key with each request. It is rolling out to pilot customers
  now — check with your Traackr contact that it is live before relying on it. See
  [Hosted server](#hosted-server).
- **Local** via `uvx traackr-api-mcp` from
  [PyPI](https://pypi.org/project/traackr-api-mcp/): runs on your machine with your
  key in the client's `env` block. See [Run it locally](#run-it-locally).

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

| Tool | Method / Path | Description |
| --- | --- | --- |
| `listCampaigns` | `GET /v1/campaigns` | List campaigns |
| `getCampaign` | `GET /v1/campaigns/{campaignId}` | Get a campaign |
| `listCampaignCreators` | `GET /v1/campaigns/{campaignId}/creators` | List creators on a campaign |
| `listCampaignPosts` | `GET /v1/campaigns/{campaignId}/posts` | List posts on a campaign |
| `getCampaignSpend` | `GET /v1/campaigns/{campaignId}/spend` | Get campaign spend totals |
| `listCampaignCreatorsSpend` | `GET /v1/campaigns/{campaignId}/creators/spend` | List per-creator spend on a campaign |
| `getCreatorSpend` | `GET /v1/campaigns/{campaignId}/creators/{creatorId}/spend` | Get a creator's spend on a campaign |
| `listCampaignCreatorDeliverables` | `GET /v1/campaigns/{campaignId}/creators/{creatorId}/deliverables` | List a creator's deliverable line items on a campaign |
| `listCampaignCreatorProducts` | `GET /v1/campaigns/{campaignId}/creators/{creatorId}/products` | List products sent to a creator |
| `getCreator` | `GET /v1/creators/{creatorId}` | Get a creator |
| `getCreatorSegments` | `GET /v1/creators/{creatorId}/segments` | Get a creator's segments |

## Hosted server

The hosted server is in pilot. It may not be reachable yet; if the URL below does not
answer, use the [local install](#run-it-locally) and ask your Traackr contact when it
goes live. Any API key that works against the Traackr API works against it — there is
no separate enablement. It speaks MCP over streamable HTTP at:

```
https://api.mcp.traackr.ai/mcp
```

Authenticate with your Traackr API key on every request, sent as an `X-Api-Key`
header (`Authorization: Bearer <key>` is accepted too). Replace `your-api-key-here`
below with your key.

### Claude Code

```bash
claude mcp add --transport http --header "X-Api-Key: your-api-key-here" \
  traackr https://api.mcp.traackr.ai/mcp
```

### Claude.ai and Claude Desktop (custom connector)

1. Open **Customize → Connectors** (Team and Enterprise owners: **Organization
   settings → Connectors**) and choose **Add custom connector**.
2. Enter `https://api.mcp.traackr.ai/mcp` as the server URL.
3. Under **Authentication** choose **No sign-in**, then add a **Request header**
   named `x-api-key` with your key as its value.
4. Click **Add**.

Request headers are rolling out in beta. If that section is missing from your
dialog, use the [local install](#run-it-locally), or ask your Traackr contact about
the [URL form](#clients-that-cannot-send-headers).

### Cursor

In `~/.cursor/mcp.json` (or a project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "traackr": {
      "url": "https://api.mcp.traackr.ai/mcp",
      "headers": { "X-Api-Key": "your-api-key-here" }
    }
  }
}
```

### Any other client

Use the streamable HTTP transport with the URL above and a custom request header
`X-Api-Key: your-api-key-here`.

### Clients that cannot send headers

A deployment can be configured to also accept the key on the URL:

```
https://api.mcp.traackr.ai/mcp?api_key=your-api-key-here
```

It is off by default, and it is a setting of the whole deployment rather than of your
account: when it is on, it is on for every caller, and the key then travels in the
URL, which proxies and access logs record. Prefer a header wherever your client
offers one, and ask your Traackr contact before relying on the URL form.

## Run it locally

The same server, installed from PyPI and run by your MCP client on your machine.

### Prerequisites

- [`uv`](https://docs.astral.sh/uv/) (provides `uvx`). Install with:
  ```bash
  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

```bash
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:

```json
{
  "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`:

```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>`:

```bash
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:

```bash
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):

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `TRAACKR_API_KEY` | yes | — | API key, sent as the `X-Api-Key` header |
| `TRAACKR_API_BASE_URL` | no | first `servers` entry in the spec | Override the API base URL (e.g. a pilot host) |
| `TRAACKR_OPENAPI_URL` | no | `https://api.traackr.ai/api/openapi/v1` | Load the OpenAPI spec from this URL (e.g. a staging spec) |

To host the server yourself instead of running it per user, three more apply:

| Variable | Default | Purpose |
| --- | --- | --- |
| `MCP_TRANSPORT` | `stdio` | `http` serves streamable HTTP at `/mcp`; callers then send their own key per request, `TRAACKR_API_KEY` must be unset, only the process environment is read, and the live spec is required |
| `MCP_HTTP_PORT` | `8080` | Listen port in `http` mode |
| `MCP_ALLOW_QUERY_API_KEY` | `false` | In `http` mode, also accept `?api_key=` on the URL for every caller (URLs get logged — leave off unless a client needs it) |

### 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 local server 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; the hosted
server never falls back, so all of its replicas serve the same tools.

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. The hosted server forwards
the key you send with each request; the local server sends the key from
`TRAACKR_API_KEY`. In both cases the key is checked by Traackr's API, so the tools see
exactly what that key is allowed to see. OAuth is planned for a future release; when
it lands, it replaces the key forwarding in
[`src/traackr_mcp/api_key.py`](src/traackr_mcp/api_key.py) without changing the tool
surface.

## Troubleshooting

- **`ERROR: TRAACKR_API_KEY is not set`** (local) — the server exits at startup rather
  than running and failing every call. Add the key to your client's `env` block (see
  [Quick start](#quick-start)) and restart the client.
- **`401 {"error":"missing_api_key", ...}`** (hosted) — the request reached the server
  without a key. Configure the `X-Api-Key` request header in your client (see
  [Hosted server](#hosted-server)); the `env` block only applies to the local install.
- **`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:
  ```bash
  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.
