Allows media buyers to manage campaigns, zones, team members, and traffic stats directly through a chat interface.
Also known as affset/mcp, mcp, @affset/mcp
- Stars
- 0
- Tools
- 31
- Downloads, 30 days
- 258
- Latest version
- 0.4.0
- Last commit
- Sep 13, 2026
- License
- MIT
What is affset MCP?
affset allows media buyers to manage campaigns, zones, team members, and traffic stats directly through a chat interface. It exposes 31 tools, such as whoami, get_stats, list_campaigns.
Summary generated from the project's README
About affset MCP server
Media buyers can manage their entire advertising workflow through a chat interface using this MCP server. It replaces traditional dashboard navigation by allowing users to pull traffic statistics, manage campaigns, and control team access using natural language. The server connects to the affset tenant API, providing a way to monitor ROI, conversions, and media costs across various dimensions like country, advertiser, or publisher.
Users can choose between a hosted remote connection via OAuth or a local installation using an npm package with a Bearer token and namespace. The hosted endpoint is compatible with Claude, Cursor, and Claude Code. For local setups, the server runs via stdio and can be configured for read-only access. The toolset includes specific commands for managing traffic sources, adjusting network bids for platforms like ExoClick or TrafficStars, and creating new zones or team members with built-in dry-run protections to prevent accidental changes.
What you can do with it
- 1Analyze campaign performanceRequest a table of traffic statistics including clicks, conversions, and ROI grouped by specific dimensions.
- 2Modify network biddingUpdate the USD bid for a specific campaign on a traffic source like RichAds or ExoClick.
- 3Manage team accessInvite a new team member to the account and assign them a specific role.
- 4Automate campaign setupCreate a new campaign with a specific offer URL, geographic targeting, and payout rate.
Written from the project's README. Every use case is checked against a quote from it.
How to install affset MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall affset MCP in Claude Code
$ claude mcp add --env 'AFFSET_API_KEY=<YOUR_AFFSET_API_KEY>' --env 'AFFSET_BASE_URL=<AFFSET_BASE_URL>' --env 'AFFSET_NAMESPACE=<AFFSET_NAMESPACE>' mcp -- npx -y @affset/mcpInstall affset MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@affset/mcp"
],
"env": {
"AFFSET_API_KEY": "<YOUR_AFFSET_API_KEY>",
"AFFSET_BASE_URL": "<AFFSET_BASE_URL>",
"AFFSET_NAMESPACE": "<AFFSET_NAMESPACE>"
}
}
}
}Install affset MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@affset/mcp"
],
"env": {
"AFFSET_API_KEY": "<YOUR_AFFSET_API_KEY>",
"AFFSET_BASE_URL": "<AFFSET_BASE_URL>",
"AFFSET_NAMESPACE": "<AFFSET_NAMESPACE>"
}
}
}
}Install affset MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@affset/mcp"],"env":{"AFFSET_API_KEY":"<YOUR_AFFSET_API_KEY>","AFFSET_BASE_URL":"<AFFSET_BASE_URL>","AFFSET_NAMESPACE":"<AFFSET_NAMESPACE>"}}'Install affset MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@affset/mcp"
],
"env": {
"AFFSET_API_KEY": "<YOUR_AFFSET_API_KEY>",
"AFFSET_BASE_URL": "<AFFSET_BASE_URL>",
"AFFSET_NAMESPACE": "<AFFSET_NAMESPACE>"
}
}
}
}Install affset MCP in Codex
$ codex mcp add mcp --env 'AFFSET_API_KEY=<YOUR_AFFSET_API_KEY>' --env 'AFFSET_BASE_URL=<AFFSET_BASE_URL>' --env 'AFFSET_NAMESPACE=<AFFSET_NAMESPACE>' -- npx -y @affset/mcpInstall affset MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@affset/mcp"] [mcp_servers.mcp.env] AFFSET_API_KEY = "<YOUR_AFFSET_API_KEY>" AFFSET_BASE_URL = "<AFFSET_BASE_URL>" AFFSET_NAMESPACE = "<AFFSET_NAMESPACE>"
Install affset MCP in Gemini CLI
$ gemini mcp add -s user -e 'AFFSET_API_KEY=<YOUR_AFFSET_API_KEY>' -e 'AFFSET_BASE_URL=<AFFSET_BASE_URL>' -e 'AFFSET_NAMESPACE=<AFFSET_NAMESPACE>' mcp npx -- -y @affset/mcpInstall affset MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@affset/mcp"
],
"env": {
"AFFSET_API_KEY": "<YOUR_AFFSET_API_KEY>",
"AFFSET_BASE_URL": "<AFFSET_BASE_URL>",
"AFFSET_NAMESPACE": "<AFFSET_NAMESPACE>"
}
}
}
}affset MCP tools 31
Detected from the READMEwhoamiget_statslist_campaignsget_campaignlist_zoneslist_teamcreate_team_membercreate_campaignset_campaign_statusupdate_campaigncreate_zoneupdate_zone
| whoami | — | |
| get_stats | — | |
| list_campaigns | — | |
| get_campaign | — | |
| list_zones | — | |
| list_team | — | |
| create_team_member | — | |
| create_campaign | — | |
| set_campaign_status | — | |
| update_campaign | — | |
| create_zone | — | |
| update_zone | — |
Show all 31 toolsShow fewer tools
list_traffic_sourcescreate_traffic_sourceupdate_traffic_sourcelist_source_bidsset_source_bidget_zone_urlget_tracking_linkcut_zoneslist_payout_rulesset_payout_ruledelete_payout_ruleset_payout_goallist_targeting_typeslist_targeting_rulesset_targeting_ruleremove_targeting_rulelist_sub_labelsset_sub_labelslist_conversions
| list_traffic_sources | — | |
| create_traffic_source | — | |
| update_traffic_source | — | |
| list_source_bids | — | |
| set_source_bid | — | |
| get_zone_url | — | |
| get_tracking_link | — | |
| cut_zones | — | |
| list_payout_rules | — | |
| set_payout_rule | — | |
| delete_payout_rule | — | |
| set_payout_goal | — | |
| list_targeting_types | — | |
| list_targeting_rules | — | |
| set_targeting_rule | — | |
| remove_targeting_rule | — | |
| list_sub_labels | — | |
| set_sub_labels | — | |
| list_conversions | — |
Configuration
AFFSET_API_KEYRequiredSecretTenant API key (Bearer token). Its namespace must match AFFSET_NAMESPACE.
AFFSET_BASE_URLRequiredOrigin of your affset ad server API (no path, query, or embedded credentials).
AFFSET_NAMESPACERequiredTenant namespace this key belongs to (lowercase letters, numbers, hyphens; 3–63 chars).
AFFSET_READ_ONLYOptional. Set to true to register only read-only tools (no create/update/delete/cut).
AFFSET_REQUEST_TIMEOUT_MSOptional per-request HTTP timeout in milliseconds (1000–300000).
| Name | Description | |
|---|---|---|
| AFFSET_API_KEY | Tenant API key (Bearer token). Its namespace must match AFFSET_NAMESPACE. | RequiredSecret |
| AFFSET_BASE_URL | Origin of your affset ad server API (no path, query, or embedded credentials). | Required |
| AFFSET_NAMESPACE | Tenant namespace this key belongs to (lowercase letters, numbers, hyphens; 3–63 chars). | Required |
| AFFSET_READ_ONLY | Optional. Set to true to register only read-only tools (no create/update/delete/cut). | |
| AFFSET_REQUEST_TIMEOUT_MS | Optional per-request HTTP timeout in milliseconds (1000–300000). |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubaffset MCP server
An MCP server that lets a media buyer run affset from a chat client — pull stats, manage campaigns/zones/team, payouts, targeting, sub labels, and cut underperforming zones in plain language, no dashboard.
The tools wrap the existing affset tenant API. Connect through the hosted
endpoint (OAuth, no API key) or run this package locally (Bearer token +
X-Namespace). One connection serves one tenant.
Fastest way to connect — the hosted endpoint. Add
https://mcp.affset.com/mcp as a remote MCP server in Claude (web or desktop),
Cursor, Claude Code, or any client that supports streamable HTTP with OAuth:
paste the URL, sign in with your affset email, keep Read-only (the consent
default) or grant full access. Every connection shows up on the dashboard
Integrations page and can be revoked individually. Setup guide:
affset.com/integrations.
The npm package below is the self-host path: same tool roster, runs on your
machine with an API key you manage yourself. Stdio defaults to full access
unless you set AFFSET_READ_ONLY=true.
Tools
| Tool | What it does |
|---|---|
whoami |
Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only. |
get_stats |
Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, advertiser, publisher, …), optionally narrowed with advertiser_email/publisher_email filters (one user, any group_by). Returns clicks, conversions, CR, payout, media cost and ROI as a table. paid_only defaults to true (same as the dashboard) so CR excludes informative conversions. Sub columns use the tenant's sub labels when configured. Per-user groupings and filters are owner/manager plus the matching side's manager role. |
list_campaigns |
List campaigns (status / name filter, pagination). |
get_campaign |
One campaign's full record — every field (untruncated offer URL, exact schedule, budgets/pacing, silent flag, payout goal type) plus its targeting rules and payout rules, in one call. |
list_zones |
List traffic-source zones (status / name filter, pagination, linked source). |
list_team |
List team members (email, role, manager). Never returns API tokens. |
create_team_member |
Invite a team member (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). A scoped manager key can only create its own managed role, self-assigned. Returns the new API key once — list_team never shows it again. Dry-run by default; confirm: true to apply. |
create_campaign |
Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, paused, global payout rule, and a ready tracking link (linked source template when configured; otherwise source_click_id={clickid} + sub placeholders). Dry-run by default; confirm: true to apply. |
set_campaign_status |
Run or pause a campaign (action: "run" | "pause"). Dry-run by default; confirm: true to apply. Running can hit the plan's active-campaign limit. |
update_campaign |
Partial update (name, offer URL, status, rate, budgets, dates, …). Dry-run by default; confirm: true to apply. Prefer set_campaign_status for run/pause. |
create_zone |
Create a traffic-source zone (name + optional postback/site/traffic-back URLs, optional traffic_source_id link). Always created active. Dry-run by default; confirm: true to apply. |
update_zone |
Partial update (name, status, URLs, traffic_source_id). Dry-run by default; confirm: true to apply. Pass null to clear a URL or unlink the source. |
list_traffic_sources |
List traffic sources — the networks bought from, each with the tracking/postback templates its linked zones use. API token shown only as set/none. |
create_traffic_source |
Create a traffic source, optionally from a network preset (exoclick, trafficstars, propellerads, adsterra, richads) that copies verified templates into an editable row. Dry-run by default; confirm: true to apply. |
update_traffic_source |
Partial update (name, templates, api_token, status). Linked zones pick the new tracking template up immediately. Dry-run by default; confirm: true to apply. |
list_source_bids |
The network campaigns of one traffic source with their current bids, read live from the network account (ExoClick, TrafficStars, RichAds — needs the source's API token): status, pricing model, bid in USD, last change that entered Affset's mutation stage. Read-only. |
set_source_bid |
Set one network campaign's bid in USD using its existing pricing model (for RichAds: CPM for pops, CPC for push/display). The dry run returns expected_current_bid; pass that value back with confirm: true to bind the write to the bid reviewed, so a concurrent change is refused rather than overwritten. Records the attempt in the source's bid history and reports applied only when the network echoes the new value. Raising a bid above 5× needs allow_large_increase: true. Dry-run by default. |
get_zone_url |
The /serve URL to paste into a network's campaign settings — rotates across the zone's active campaigns. A zone linked to a traffic source renders that source's tracking template; otherwise prefilled sub convention + optional cost macro. Warns when no active campaigns are visible. |
get_tracking_link |
The /track/click link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Renders a linked source's template like get_zone_url. Re-derives what create_campaign echoed on create. |
cut_zones |
Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). Dry-run by default; confirm: true to apply. |
list_payout_rules |
List a campaign's global + per-zone payout rules and its payout_goal_type. |
set_payout_rule |
Upsert a global or zone-specific payout. Dry-run by default; confirm: true to apply. |
delete_payout_rule |
Delete a global or zone-specific payout rule. Dry-run by default; confirm: true to apply. |
set_payout_goal |
Set or clear payout_goal_type (goal-based conversions). Dry-run by default; confirm: true to apply. |
list_targeting_types |
Catalog of targeting rule types, flagging the seeded ones /serve never evaluates. |
list_targeting_rules |
List a campaign's targeting rules, flagging any that have no effect. |
set_targeting_rule |
Upsert one targeting rule (safe merge), normalised to what /serve matches. Dry-run by default; confirm: true to apply. |
remove_targeting_rule |
Remove one targeting rule by id or type+method. Dry-run by default; confirm: true to apply. |
list_sub_labels |
List tenant display names for sub1–sub5. |
set_sub_labels |
Set or clear sub labels (partial; null clears). Dry-run by default; confirm: true to apply. |
list_conversions |
List conversion audit records (payout, spend, pixel type, payload, postback). paid_only filters server-side; other optional filters are client-side on the current page. |
Which URL do I give the network?
get_zone_url (/serve/{zone}) |
get_tracking_link (/track/click/{campaign}/{zone}) |
|
|---|---|---|
| Picks the campaign | affset, from the zone's rotation | you, one fixed campaign |
| Needs an active campaign | yes — otherwise traffic back / unsold | yes — otherwise 404 |
| Needs an active zone | yes | yes |
| Geo & targeting rules | enforced | not enforced |
cost= lands on |
the impression row | the click row |
Use one or the other for a given traffic stream — never both with cost=, or the
media cost is counted twice.
Both use the tenant's custom API domain when one is set, since the URL gets pasted
into the network verbatim. Macros ({clickid}, [CLICK_ID], ${SUBID}) are inserted
without percent-encoding — the source expands them before the request reaches affset.
cut_zones only ever adds zones to a campaign's blacklist, and does a
read-merge-write so existing targeting rules are never touched.
create_campaign needs a traffic-source zone for the tracking link: pass
zone_id, or let it auto-pick when the namespace has exactly one active zone.
Campaigns are created paused; activate them before sending traffic through either
URL. Both URL types also require an active zone. Geo whitelist is enforced in /serve
only — the direct tracking link is not geo-gated, but it still requires an active,
currently serviceable campaign.
Documentation resources
Beyond the tools, the server exposes the affset API reference as MCP
resources, so an
assistant can answer "how does conversion tracking work?" or "what does /serve
accept?" from the docs themselves — not just from the tool schemas.
| Resource URI | Type | Content |
|---|---|---|
affset://docs/api-reference |
text/markdown |
The full API reference — endpoints, auth, roles, examples. |
affset://docs/api-reference.json |
application/json |
The same reference as structured data, for programmatic use. |
They're the exact content published at affset.com/docs,
generated from one source, and fetched at read time from AFFSET_DOCS_URL
({origin}/api-reference.md and {origin}/api-reference.json) — so they always
reflect the currently published docs, not a copy pinned to this package. The
fetch sends no credentials (the docs are public and live on a different
origin than the tenant API). HTML SPA fallbacks, redirects, invalid JSON, and
oversized bodies are rejected. Both resources are always available, including
under AFFSET_READ_ONLY.
affset MCP questions
How do I add affset MCP to Claude Code?
Run claude mcp add --env 'AFFSET_API_KEY=<YOUR_AFFSET_API_KEY>' --env 'AFFSET_BASE_URL=<AFFSET_BASE_URL>' --env 'AFFSET_NAMESPACE=<AFFSET_NAMESPACE>' mcp -- npx -y @affset/mcp in your terminal. Add --scope user to make it available in every project.
How do I add affset MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does affset MCP provide?
It exposes 31 tools, including whoami, get_stats, list_campaigns, get_campaign, list_zones.
Can I run this server locally?
Yes, you can run the npm package locally using a Bearer token and X-Namespace.
What kind of statistics can I retrieve?
You can pull traffic stats including clicks, conversions, CR, payout, media cost, and ROI, grouped by dimensions like date, campaign, or country.