MCP server

The Model Context Protocol server lets any MCP-compatible AI client read your spend data, pause campaigns, adjust budgets, and more. The same guardrails that apply to CLI commands apply here.

Quick setup for Claude Desktop

The fastest path is adduck agents install:

adduck agents install --client claude

This writes the server entry into ~/Library/Application Support/Claude/claude_desktop_config.json and prints confirmation. Restart Claude Desktop after running it.

Manual setup

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "adduck": {
      "command": "adduck",
      "args": ["mcp"],
      "env": {
        "ADDUCK_CONFIG": "/path/to/your/adduck.json"
      }
    }
  }
}

If your adduck.json is in a standard location, you can omit the env block and adduck will use the active project.

Setup for Cursor

adduck agents install --client cursor

Writes to ~/.cursor/mcp.json. Same format as Claude Desktop.

Other MCP clients

Any client that supports stdio MCP servers can use adduck. The command is just adduck mcp. Check your client's documentation for where to add server definitions.

Available tools

All tool names follow snake_case. Parameters are JSON.

get_spend

Returns spend, installs, taps, and CPI for connected platforms over a date range.

Parameter	Type	Description
days	number	Number of trailing days. Default: 7.
platform	string	Optional. Limit to one platform.
start	string	Optional. Start date in YYYY-MM-DD. Overrides `days`.
end	string	Optional. End date in YYYY-MM-DD.

list_campaigns

Returns all campaigns with their IDs, status, and daily budgets.

Parameter	Type	Description
platform	string	Optional. Limit to one platform.
status	string	Optional. One of: `active`, `paused`, `all`. Default: `all`.

inspect_campaign

Returns detailed data for a single campaign including daily spend breakdown.

Parameter	Type	Description
platform	string	Required. Platform name.
campaignId	string	Required. Campaign ID from that platform.
days	number	Days of history to include. Default: 7.

pause_campaign

Pause one or more campaigns. Blocked if the campaign is in protectedCampaigns or if allowMutations is false.

Parameter	Type	Description
platform	string	Required.
campaignIds	string[]	Required. Array of campaign IDs.

resume_campaign

Resume one or more paused campaigns.

Parameter	Type	Description
platform	string	Required.
campaignIds	string[]	Required.

set_budget

Set the daily budget for a campaign. Checked against maxBudgetChangePct and maxDailyBudgetMicros.

Parameter	Type	Description
platform	string	Required.
campaignId	string	Required.
dailyBudget	number	Required. Amount in whole dollars.

get_guardrails

Returns the current guardrail configuration. No parameters. Useful for an AI assistant to check what it's allowed to do before attempting a mutation.

list_schedules

Returns all configured schedules with their IDs, actions, and enabled state.

Parameter	Type	Description
platform	string	Optional. Filter by platform.

run_audit

Runs the same checks as adduck audit and returns pass/fail for each guardrail rule. No parameters.

Error responses

When a tool call fails (guardrail violation, API error, unknown campaign ID), the tool returns an object with error: true and a message field. Well-behaved AI clients will surface this to the user rather than silently failing.

{
  "error": true,
  "code": "GUARDRAIL_VIOLATION",
  "message": "Cannot set daily budget to $600: exceeds maxDailyBudgetMicros of $500.00"
}

What the AI can and can't do

The MCP tools give the AI the same permissions as the CLI, subject to guardrails. Specifically:

It can read spend data, campaign lists, and guardrail config without restriction
It can pause, resume, and change budgets only if allowMutations: true
It can't increase a budget past maxDailyBudgetMicros
It can't change a campaign by more than maxBudgetChangePct in one call
It can't touch campaigns in protectedCampaigns
It has no access to credentials or the ability to add/remove platforms

Example conversation

Claude Desktop

You: What's my CPI looking like across networks this week?

Claude: [calls get_spend with days=7]

Your 7-day CPI by network:
  Meta: $2.86 (71 installs)
  Apple: $3.02 (47 installs)
  Reddit: $4.05 (22 installs)

Reddit is running at $4.05 CPI while Meta is at
$2.86. Want me to pause Reddit or just lower the
budget while you evaluate?

You: Pause it.

Claude: [calls pause_campaign for reddit]
  ✓ Paused "App Awareness Q3" on Reddit Ads.