AttriKit

@attrkit/mcp

适用于 AttriKit 的标准输入/输出 MCP 服务。AttriKit 为投放广告的 iOS 和 Android 应用提供从 Web 到应用的归因功能。可通过 Claude Code、 Claude Desktop、Codex、Cursor、Gemini CLI、VS Code 或 Windsurf 使用它来创建广告系列链接、 导入花费、查看各广告系列的扩量、暂停或维持建议，并导出安装和事件数据。 它是 AttriKit 公共 API 的轻量客户端。不持有数据库访问权限；租户范围 由你的密钥管理密钥确定。

源代码：KamyarTaher/attrikit-mcp。请在那里或通过 [email protected] 报告问题。采用 MIT 许可。

提供的功能

此服务提供 39 个工具。

类别	工具
密钥范围	whoami
工作区用量	get_usage_cap、set_usage_cap
应用	list_apps、create_app、get_app、update_app、archive_app
SDK 密钥	get_publishable_key、rotate_publishable_key
管理密钥	list_api_keys、create_api_key、revoke_api_key
广告系列链接	list_links、create_campaign_link、update_link_status
决策与报告	list_campaigns、list_ads、list_recent_events、list_event_deliveries、get_campaign_decision、record_campaign_decision、get_attribution_rollup、lookup_customer_attribution
花费与成本	get_spend、import_spend、set_cost_model、pull_network_spend
广告集成	list_integrations、create_integration、update_integration、delete_integration
RevenueCat	get_revenuecat、configure_revenuecat
出站 Webhook	list_webhooks、create_webhook、delete_webhook
数据导出	export_events
服务端事件	send_server_event

get_campaign_decision 会原样返回引擎给出的决策。模型只会报告该决策， 不会重新计算。

Meta 或 TikTok 集成有两种投递选项。delivery_scope 可以设为 all （默认值：所有获得测量同意的安装，包括自然安装）或 attributed（仅限 AttriKit 归因到该网络的安装：具有点击 ID、链接令牌，或达到投递门槛的 Matched 安装）。renewal_event 可以设为 purchase（默认值：续订作为 Purchase 发送）或 custom（作为自定义事件 subscription_renewed 发送，并附带其价值）。可在 create_integration 时设置这些选项，也可稍后通过 update_integration 和操作 set_delivery_options 设置；该操作不会更改凭据和状态。Google 集成不允许使用 attributed 和 custom。

连接前准备

安装 Node.js 22 或更高版本。npx -y @attrkit/mcp 命令会自动下载并 启动服务，因此无需全局安装。

从 2.0.0 开始需要 Node.js 22。 engines.node 为 >=22；1.x 支持 Node.js 18。 如果客户端仍使用较旧版本的 Node 启动服务，请升级 Node，或固定使用 @attrkit/mcp@1。工具及其输入和输出均未更改。

请先在 Dashboard → Settings → API keys & MCP 下创建第一个工作区管理密钥。此一次性引导操作需要通过 Dashboard 完成。

创建第一个密钥后，具备工作区范围的读写密钥即可管理管理 API 提供的所有客户操作，包括应用、 委派密钥、用量上限、集成和导出。

如果客户端需要较少的访问权限，请使用只读密钥或应用范围密钥。应用范围密钥无法读取或更改工作区用量上限、创建同级应用，或 管理整个工作区的集成。

向服务提供密钥

在 macOS 上，将密钥保存到钥匙串一次即可：

npx -y @attrkit/mcp login

它会在关闭回显的情况下提示输入密钥，向 AttriKit 验证密钥（并打印套餐和权限范围）， 然后将密钥保存到钥匙串条目 attrkit-mcp 中。密钥不会出现在进程列表中。 npx -y @attrkit/mcp logout 会移除该条目。

在任何系统上，你也可以在启动 MCP 客户端的进程环境中设置 ATTRKIT_API_KEY， 或将它保存在客户端自己的密钥存储中。

启动时，服务会按以下顺序解析密钥：

1. ATTRKIT_API_KEY，前提是它具有实际值。
2. 在 macOS 上，钥匙串条目 attrkit-mcp。空的 ATTRKIT_API_KEY，或客户端未展开的值 （$ATTRKIT_API_KEY、${ATTRKIT_API_KEY}、${ATTRKIT_API_KEY:-}、 ${env:ATTRKIT_API_KEY}、${input:attrkit-key}），都视为未设置。
3. 否则，服务会退出并显示指出解决方法的错误。

Codex

将此服务添加到 ~/.codex/config.toml：

[mcp_servers.attrkit]
command = "npx"
args = ["-y", "@attrkit/mcp"]
env = { ATTRKIT_API_URL = "https://attrikit.io" }
env_vars = ["ATTRKIT_API_KEY"]

codex mcp get attrkit

请参阅 Codex 设置指南。

Cursor

将服务添加到单个项目的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以用于所有项目：

{
  "mcpServers": {
    "attrkit": {
      "command": "npx",
      "args": ["-y", "@attrkit/mcp"],
      "env": {
        "ATTRKIT_API_KEY": "${env:ATTRKIT_API_KEY}",
        "ATTRKIT_API_URL": "https://attrikit.io"
      }
    }
  }
}

然后启用它并查看可用工具：

cursor-agent mcp list
cursor-agent mcp list-tools attrkit

请参阅 Cursor 设置指南。

Gemini CLI

将此服务添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "attrkit": {
      "command": "npx",
      "args": ["-y", "@attrkit/mcp"],
      "env": {
        "ATTRKIT_API_KEY": "$ATTRKIT_API_KEY",
        "ATTRKIT_API_URL": "https://attrikit.io"
      }
    }
  }
}

gemini mcp list

请参阅 Gemini 设置指南。

其他 MCP 客户端

配置一个 stdio 服务，命令为 npx，参数为 ["-y", "@attrkit/mcp"]，并设置 ATTRKIT_API_KEY 环境变量。 不同客户端的环境变量插值方式各不相同，请遵循相应客户端关于密钥处理的文档。 ATTRKIT_API_URL 为可选项，默认值为 https://attrikit.io。

字段命名

工具输入架构使用 snake_case（bundle_id、store_url、campaign_id）， 也可作为 REST 文档：Management API 在查询字符串和 JSON 请求正文中接受相同的 snake_case 字段名（camelCase 也可用），响应始终使用 snake_case。若验证失败可归因于 特定字段，字段级详细信息会返回在 error.fields 下。格式错误的 JSON 没有可指出的字段。 对于 invalid_cursor、invalid_url 和 ssrf_blocked 等可自行说明原因的拒绝， 只会返回错误代码。

在本地测试

ATTRKIT_API_KEY=sk_... npx @modelcontextprotocol/inspector npx -y @attrkit/mcp

Inspector 会列出工具，并允许你对实时工作区调用这些工具。

访问权限边界

控制项	Management API 和 MCP
首次获取密钥后的客户操作	可使用限定工作区范围的读写密钥
第一个工作区管理密钥	仅可通过控制面板引导创建
账单和订阅	不可用
登录和组织成员资格	不可用
工作区删除	不可用
内部管理	不可用

请参阅 Management API 指南和 OpenAPI 契约，了解完整的 HTTP 接口。

说明

• 仅支持 stdio。此软件包不会开放网络端口。
• 密钥的作用域控制读取与写入权限。只读密钥对每项变更操作都会收到 403 forbidden_scope。
• 应用级密钥无法创建其他应用、访问同级应用或管理工作区级集成。
• 创建应用、管理密钥和 webhook 时，密钥值只会返回一次。请从工具结果中保存；列表工具仅返回经过遮蔽的元数据。
• 除移除操作外，变更工具均接受可选的 idempotency_key。仅在完全相同的重试中重用同一值。一次性密钥响应在静态存储时会加密，并可安全重放。移除工具不接受此参数，因为其 DELETE 操作无法重复执行移除。
• 管理密钥受分布式的每密钥全局限流、变更操作限流和高开销操作限流保护。429 响应包含 Retry-After；重试前至少等待相应秒数。
• 所有诊断信息都会发送到 stderr。stdout 专用于 MCP 传输。
• MCP 客户端会将环境值保存在本地配置中。切勿提交包含密钥的配置。请限制对文件的访问，并撤销任何已泄露的密钥。

迁移到 1.0.0

1.0.0 版本规范了工具输入架构、完善了运行时配置验证，并引入了相较于 0.4.6 版本的三项破坏性限制：

1. import_spend 中的广告标识符必须成对提供：现在必须同时提供 adset_id 和 ad_id（及其驼峰命名别名 adsetId 和 adId），或两者都省略。在 0.4.6 版本中，架构允许单独提供任一字段，但底层 API 会拒绝不成对的调用；1.0.0 版本将此验证移至客户端。
2. record_campaign_decision 中的 campaign_id 必须采用严格的 UUID 格式：现在 campaign_id 必须是有效的 RFC 4122 UUID。0.4.6 版本接受任意非空字符串。
3. readConfig 中的 API 基础 URL（ATTRKIT_API_URL）必须通过严格验证：readConfig 会拒绝以下四种情况，并在启动时终止（违规信息会输出到 stderr，并以代码 1 退出）：
   • 协议拒绝：不接受非环回 HTTP 端点（protocol must be HTTPS, except HTTP is allowed for localhost development）。仅环回接口（localhost、127.0.0.1、[::1]）允许使用 HTTP；远程主机必须使用 https:。
   • 凭据拒绝：不接受 URL 中嵌入的基本身份验证凭据（credentials are not allowed in ATTRKIT_API_URL）。请通过 ATTRKIT_API_KEY 传递 API 身份验证信息。
   • 查询字符串拒绝：不接受基础 URL 中的查询参数（query strings are not allowed in ATTRKIT_API_URL）。
   • 片段拒绝：不接受基础 URL 中的片段标识符（fragments are not allowed in ATTRKIT_API_URL）。 （此外，无法通过 URL 解析的格式错误字符串会抛出 Invalid URL，并以代码 1 退出。）

此外，在 0.4.6 风格的编码方式下，点号路径段 ID 会逸出应用路由；1.0.0 会确保这些 ID 始终留在路由内，涵盖全部七个应用工具（get_app、update_app、archive_app、get_publishable_key、rotate_publishable_key、get_revenuecat 和 configure_revenuecat）。

完整的发布详情请参阅 CHANGELOG.md。

许可证

MIT。请参阅 LICENSE。