Metadata-Version: 2.5
Name: traackr-api-mcp
Version: 0.2.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
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. 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](https://pypi.org/project/traackr-api-mcp/) 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.

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

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

### 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`](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](#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:
  ```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.

