# stackadapt-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for querying [StackAdapt's](https://www.stackadapt.com) GraphQL API. Gives AI assistants like Claude direct access to your campaign data, delivery metrics, advertisers, and more.

## Tools

| Tool | Description |
|------|-------------|
| `list_campaigns` | List campaigns with optional filters (campaign group, advertiser) |
| `get_campaign` | Get detailed campaign info — targeting, budget, flight dates, ads |
| `get_campaign_group` | Get campaign group details — flights, budget, frequency caps, child campaigns |
| `campaign_delivery` | Pull performance metrics per campaign (impressions, clicks, spend, CTR, ATOS, engagements) with date range and granularity |
| `campaign_group_delivery` | Same metrics aggregated at the campaign group level |
| `list_advertisers` | List advertisers on the account |
| `list_campaign_groups` | List campaign groups with advertiser info |
| `graphql_query` | Execute any custom GraphQL query against the StackAdapt API |

## Setup

### Get your API key

StackAdapt API key from: **StackAdapt Platform → Settings → API**.

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stackadapt": {
      "command": "npx",
      "args": ["-y", "stackadapt-mcp"],
      "env": {
        "STACKADAPT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "stackadapt": {
      "command": "npx",
      "args": ["-y", "stackadapt-mcp"],
      "env": {
        "STACKADAPT_API_KEY": "${STACKADAPT_API_KEY}"
      }
    }
  }
}
```

Then set the env var in your shell: `export STACKADAPT_API_KEY=your-api-key-here`

## Data notes

A few things to know about StackAdapt's API:

- **`cost`, `ecpc`, `ecpm`, `ecpe`** are returned as strings — parse them as floats
- **`ctr`** is already a percentage value (0.214 means 0.214%) — don't multiply by 100
- **`ecpe`** returns `"0"` for periods with zero engagements
- **Delivery payloads** are GraphQL UNION types (`Outcome | Progress`) — large queries may return a `Progress` response with a job ID; retry after a few seconds
- **Granularity options**: `DAILY`, `WEEKLY`, `MONTHLY`, `TOTAL`

## Development

```bash
git clone https://github.com/aymanshaikh/stackadapt-mcp.git
cd stackadapt-mcp
npm install
npm run build
```

To test locally, set `STACKADAPT_API_KEY` and run:

```bash
STACKADAPT_API_KEY=your-key node dist/index.js
```

## License

MIT