{
  "markdown": "# AdButler MCP Server\n\n[![npm](https://img.shields.io/npm/v/@adbutler/mcp-server.svg)](https://www.npmjs.com/package/@adbutler/mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nManage your entire AdButler account from any AI assistant — Claude, ChatGPT, Cursor, Windsurf, Cline, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.\n\nThis MCP server exposes the **full AdButler v2 API** — 600+ tools covering advertisers, campaigns, zones, creatives, placements, VAST video ads, programmatic / RTB, reporting, targeting, drafts, contracts, product catalogs, and more — plus 9 pre-built workflow prompts that walk an AI through common tasks like launching a campaign or setting up retail media.\n\n## What you can ask\n\n> \"Create a new campaign for Pepsi targeting users in Canada with a $5,000 lifetime budget, and assign it to my Homepage Banner zone.\"\n\n> \"Show me the top 10 underperforming ad items in the last 7 days by CTR.\"\n\n> \"Set up a VAST 4.2 pre-roll campaign with a 30-second skippable creative and three companion banners.\"\n\n> \"Walk me through creating a new programmatic deal.\"\n\n> \"Audit my ad units — which zones have no active placements?\"\n\nThe AI translates these into the right sequence of AdButler API calls, runs them, and shows you the result.\n\n## Install\n\nYou have two options. **Most users want the hosted version** — zero setup, just paste a URL.\n\n### Option A — Hosted (recommended)\n\nUse AdButler's hosted MCP server. No install, no Node, no npm.\n\nThe hosted server speaks both modern **Streamable HTTP** (`/mcp`) and legacy **SSE** (`/sse`) transports. New clients should prefer Streamable HTTP; SSE remains for backward compatibility.\n\n| Client | Configuration |\n|--------|---------------|\n| **Claude Desktop / Code** | Add an MCP server with URL `https://mcp.adbutler.com/mcp` (or `/sse` for older clients) and header `Authorization: Bearer YOUR_ADBUTLER_API_KEY` |\n| **Cursor** | Settings → Features → Model Context Protocol → Add server with the URL + auth header above |\n| **Any MCP client** | Streamable HTTP: `https://mcp.adbutler.com/mcp`  ·  SSE: `https://mcp.adbutler.com/sse` — pass your API key via `Authorization: Bearer …` or `?api_key=…` |\n\n### Option B — Local stdio (npm)\n\nRun the server locally as a Node process. Useful if you want to keep your API key out of any external service or run against a self-hosted AdButler.\n\n#### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"adbutler\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adbutler/mcp-server\"],\n      \"env\": {\n        \"ADBUTLER_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Code\n\n```bash\nclaude mcp add adbutler --env ADBUTLER_API_KEY=your_api_key_here -- npx -y @adbutler/mcp-server\n```\n\n#### Cursor / Windsurf / Cline\n\nAdd to the client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"adbutler\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adbutler/mcp-server\"],\n      \"env\": { \"ADBUTLER_API_KEY\": \"your_api_key_here\" }\n    }\n  }\n}\n```\n\n## Get your AdButler API key\n\nAdButler Dashboard → **Settings → API Keys** → create a new key. It's the same key the AdButler v2 REST API uses.\n\n## Authentication\n\nThe AdButler MCP works for both new and existing customers. What you see depends on whether you've already configured an API key.\n\n### Already an AdButler customer? (existing API key)\n\nUse one of these:\n\n**Option 1 — set the API key in your connection config (recommended: persists across sessions)**\n\nPass the key at connect time and every session authenticates automatically — the key never has to be shared in the chat.\n\n- **Claude Code** — `claude mcp add adbutler --transport http https://mcp.adbutler.com/mcp --header \"Authorization: Bearer YOUR_API_KEY\"`\n- **Claude Desktop** — edit `claude_desktop_config.json` → add `headers: { \"Authorization\": \"Bearer YOUR_API_KEY\" }` next to the server URL\n- **Cursor** — MCP server settings → Headers → add `Authorization: Bearer YOUR_API_KEY`\n- **claude.ai custom connectors** (no custom-header support) — use the URL form: `https://mcp.adbutler.com/mcp?api_key=YOUR_API_KEY`\n- **Any client** — `Authorization: Bearer …` header or `?api_key=…` query param, on `/mcp` (Streamable HTTP) or `/sse` (legacy SSE)\n\nReconnect — all 600+ tools become available immediately.\n\n**Option 2 — configure inside the chat (current session only on hosted)**\n\nConnect to the hosted MCP without auth and you'll see four onboarding tools. Then in the chat say:\n\n> \"Configure my AdButler API key: `your_api_key_here`\"\n\nYour AI will call the `setup_api_key` tool, validate the key against your account, and unlock all the AdButler tools. You may need to disconnect and reconnect to refresh your client's tool list after.\n\n> ⚠️ On the hosted server, a key configured this way lasts **only until the session ends** — a new chat, a client restart, or a server-side reconnect will ask for it again. If you find yourself pasting the key into the chat repeatedly (and your AI warning you about sharing secrets in conversation), switch to Option 1: configure the key once in the connection settings and it persists.\n\n### Troubleshooting: \"my API key won't stay configured\"\n\nThis means the key is being entered in-chat (Option 2) against the hosted server, where it is deliberately session-scoped — the hosted server is multi-tenant and never writes your key to disk. The fix is one-time setup in your client's connection config (Option 1 above): header for Claude Code / Claude Desktop / Cursor, `?api_key=` URL parameter for claude.ai custom connectors. After that, reconnects and new chats authenticate automatically.\n\n### New to AdButler? (no account yet)\n\nConnect to the hosted MCP without auth. The chat will guide you through a free trial signup using `create_trial_account` → check your email → `verify_trial_email` with the code. The API key is configured automatically.\n\n### Local stdio install\n\nIf you're running locally via `npx`, set `ADBUTLER_API_KEY` in the env block of your client's MCP config (see Option B above). The setup tools also work — and on local the key is remembered between sessions.\n\n## What's included\n\n### 9 workflow prompts\n\nPre-built skill prompts that guide the AI through complete workflows end-to-end. Invoke them as MCP prompts (`/launch-campaign` etc.) from your client.\n\n| Prompt | What it does |\n|--------|--------------|\n| `launch-campaign` | Walks an end-to-end campaign launch — advertiser → campaign → ad items → creatives → targeting → placements |\n| `retail-media-setup` | Sets up sponsored products / retail media for an e-commerce site |\n| `reporting` | Generates a custom report with the right dimensions and filters |\n| `vast-video` | Builds a VAST video ad with linear + companion creatives |\n| `programmatic` | Configures programmatic deals, bidders, and demand sources |\n| `targeting` | Builds geo / platform / data-key / list targets |\n| `contracts` | Creates IO contracts and assigns them to campaigns |\n| `channels` | Bundles zones into a channel and assigns campaigns |\n| `drafts` | Stages a complete campaign as drafts before going live |\n\n### 3 fallback meta-tools (search, describe, call)\n\nWhen you need an endpoint that no specific tool wraps — or when the user asks about a *field* (e.g. \"priority\", \"frequency cap\") rather than a resource — three escape-hatch tools cover the gap:\n\n| Tool | What it does |\n|------|--------------|\n| `search_adbutler_api` | Keyword-search the full AdButler OpenAPI spec for matching endpoints |\n| `describe_adbutler_api` | Get the full schema (params, body, response) for one endpoint |\n| `call_adbutler_api` | Invoke any endpoint by method+path, with the session's auth applied automatically |\n\nThese complement (don't replace) the specific tools below — the LLM continues to prefer specific tools when they obviously match.\n\n### 600+ tools across the full AdButler API\n\n| Domain | Tools | Examples |\n|--------|------:|----------|\n| **Display ads** | 100+ | `list_advertisers`, `create_campaign`, `create_image_ad_item`, `create_native_ad_item`, `create_placement`, `create_schedule`, `create_campaign_assignment` |\n| **VAST 2/3/4 video** | 156 | `vast_create_creative`, `vast_create_linear_media`, `vast_create_companion`, `vast_create_placement`, `vast_create_schedule`, plus full VAST 4.2 sub-resource coverage |\n| **Zones & publishing** | 50+ | `create_zone`, `create_zone_catalog`, `create_zone_email`, `create_native_template`, `create_publisher`, ORTB native assets |\n| **Targeting** | 37 | `create_geo_target`, `create_platform_target`, `create_data_key`, `create_data_list`, `create_postal_code_target` |\n| **Reporting** | 39 | `get_display_report`, `get_vast_report`, `get_event_logs`, custom report configs, scheduled reports |\n| **Programmatic / RTB** | 25 | `create_demand_source`, `create_demand_endpoint`, `create_bidder`, `create_pmp_deal` |\n| **Product catalogs** | 20 | `create_product_db_catalog`, `bulk_upload_products`, ad item ↔ catalog item linking |\n| **Drafts** | 48 | Stage campaigns/ad items/placements/schedules as drafts; publish atomically |\n| **Contracts** | 43 | Insertion orders, contract documents, signature requests, payments |\n| **Account & security** | 27 | Users, roles, redirect domains, beacon signing keys, SFTP connections |\n| **Ad serving** | 2 | `serve_ad`, `live_website_preview` |\n\n100% coverage of the AdButler [v2 OpenAPI spec](https://api.adbutler.com/openapi.json) (604/604 endpoints).\n\n## Telemetry\n\nThe **hosted** server at `mcp.adbutler.com` collects usage analytics so we can understand which tools are popular, prioritize improvements, and diagnose failures. We capture, per tool call:\n\n- Tool name (e.g. `list_zones`, `create_campaign`) — never tool arguments\n- Account ID (derived once per session from `/self`)\n- API-key fingerprint (SHA-256, truncated to 16 hex chars) — identifies which key was used **without** storing the key itself\n- Transport (HTTP or SSE), MCP client name and version (e.g. Claude Desktop), call duration, success/error status\n- On errors: upstream HTTP status code, a categorical error class (e.g. `forbidden`, `network`), and the error message text (truncated to 1000 characters)\n\nWe **never** collect: tool arguments, response bodies, your raw API key, IP addresses, request bodies. The instrumentation only sees the tool name, timing, and (on failure) the error message produced by the MCP server or AdButler API.\n\n**Self-installed copies — npm package, stdio, your own deployment — collect zero data.** The instrumentation only fires when the `ANALYTICS_INGEST_URL` environment variable is set, which is only true for the hosted endpoint at mcp.adbutler.com.\n\nIf you'd prefer to opt out of analytics on the hosted server, run your own copy via stdio or self-host the SSE/HTTP server.\n\n## Development\n\nLocal source for contributors:\n\n```bash\ngit clone https://github.com/adbutler/mcp-server\ncd mcp-server\nnpm install\nnpm run build\nADBUTLER_API_KEY=your_key node dist/index.js\n```\n\nInspect with the official MCP inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Resources\n\n- **AdButler API documentation** — https://api.adbutler.com/openapi.json\n- **MCP Protocol** — https://modelcontextprotocol.io\n- **Hosted server status** — https://mcp.adbutler.com/health\n- **Issues / feature requests** — https://github.com/adbutler/mcp-server/issues\n\n## License\n\nMIT\n",
  "bytes": 11543,
  "sha": "be1e63ae3980d888c82c50686816f7712e09e3ae6bd523319c0f62bb769d1235",
  "repo_slug": "adbutler/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_adbutler_mcp_server_8672baf6/readme"
}