Kadam Ad Network

@kadam-net/mcp-server

用于 Kadam 广告网络的 MCP 服务，可通过 AI Agent 管理广告系列、创意素材、受众、网站和分析数据。

基于 Model Context Protocol（MCP）构建。MCP 是连接大模型与外部工具和数据的开放标准。

一键安装

Cursor

或手动添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

Claude Code

claude mcp add kadam -- npx -y @kadam-net/mcp-server

然后设置环境变量：export KADAM_ADV_API_KEY=your-key

Claude Desktop

下载 → 双击 → 安装。或手动添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

任何 MCP 客户端（通用单行命令）

npx add-mcp @kadam-net/mcp-server

Docker

docker run -i --rm \
  -e KADAM_ADV_API_KEY=your-key \
  kadam/mcp-server:latest

全局安装 npm 包

npm install -g @kadam-net/mcp-server
KADAM_ADV_API_KEY=your-key kadam-mcp-server

配置

变量	必填	描述
KADAM_ADV_API_KEY	二选一	从 partners.kadam.net -> Profile -> API 获取的广告主 API 密钥
KADAM_PUB_API_KEY	二选一	从 pub.kadam.net -> Profile -> API 获取的发布商 API 密钥
KADAM_ADV_API_BASE	否	广告主 API URL（默认：https://partners.kadam.net/api/v1）
KADAM_PUB_API_BASE	否	发布商 API URL（默认：https://pub.kadam.net/api）
LOG_LEVEL	否	日志级别：trace、debug、info、warn、error、fatal（默认：info）

stdio 模式下必须至少提供一个 API 密钥。在 HTTP 模式下，令牌通过 Bearer 身份验证随每个请求传递。

基于角色的目录

工具目录与令牌持有者的角色相匹配。每个会话（在 stdio 模式下为每个进程）服务器会调用一次广告主 API 的 GET /api/v1/access，该 API 会返回 { impersonation: bool }：

令牌持有者	impersonation	目录
广告主 API 密钥，或仅包含 sub 的账户 JWT	false	75 个工具；create_campaign / update_campaign 不包含仅限经理使用的字段
包含 act.sub 的账户 JWT（代表客户操作的 Kadam 经理）	true	80 个工具（增加下文标记为“仅限经理使用”的 5 个工具）；广告系列写入操作接受 hasCorrectPostback、isDirectTrafficPriority、allowMultiAds
发布商 API 密钥	n/a	17 个发布商工具；发布商 API 不支持 impersonation

这只是目录提示，不是访问限制：Kadam API 会在每次调用时执行相同规则（客户端令牌会收到 403 / 422）。如果无法访问 /access，会话将使用客户端目录——较小的目录始终可以安全展示。

HTTP 传输（多租户部署）

用于为多个用户提供服务的服务器端部署：

变量	必填	描述
MCP_TRANSPORT	否	"stdio"（默认）或 "http"
MCP_HTTP_PORT	否	HTTP 端口（默认值：8080）
MCP_HTTP_HOST	否	绑定地址（默认值：0.0.0.0）
KADAM_ADV_DOMAIN	否	用于 PRM 的广告主域名（默认值：https://partners.kadam.net）
KADAM_PUB_DOMAIN	否	用于 PRM 的发布商域名（默认值：https://pub.kadam.net）

docker run -d --name kadam-mcp \
  -e MCP_TRANSPORT=http \
  -p 8080:8080 \
  kadam/mcp-server:latest

通过 HTTP 连接（Cursor / Claude）

{
  "mcpServers": {
    "kadam-adv": {
      "url": "https://partners.kadam.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADV_API_KEY"
      }
    }
  }
}

通过 OAuth 连接（ChatGPT）

在 ChatGPT 设置中，将 https://partners.kadam.net/mcp（广告主）或 https://pub.kadam.net/mcp（发布商）添加为服务器 URL。OAuth 发现、注册和登录会自动完成。

工具（80 个）

广告主工具（63 个）

需要 KADAM_ADV_API_KEY。

词典

工具	描述	注解
kadam_adv_get_dictionary	参考词典：广告系列类型、浏览器、平台、设备、连接、类别、ISP、转化模板、国家、地区、城市	只读

广告系列

工具	描述	注释
kadam_adv_list_campaigns	按筛选条件（文件夹、状态、类型、日期、搜索）和分页列出广告系列	readOnly
kadam_adv_get_campaign	按 ID 获取完整的广告系列配置：落地页 URL、各国家/地区的出价、预算、定向、频次上限、排期、转化设置	readOnly
kadam_adv_create_campaign	创建广告系列并设置完整定向（国家/地区、设备、操作系统、浏览器、年龄、性别、受众）；dryRun: true 仅进行验证	—
kadam_adv_update_campaign	按 ID 更新广告系列的任意字段	—
kadam_adv_set_campaign_status	按逗号分隔的 ID 批量更改状态（启用／暂停／归档／恢复）；报告每个 ID 的结果	idempotent
kadam_adv_delete_campaigns	按逗号分隔的 ID 批量删除已归档的广告系列；需要 confirm: true，并报告每个 ID 的结果	destructive
kadam_adv_move_campaigns	按逗号分隔的广告系列 ID 和目标组 ID，将广告系列移至某个广告系列组	idempotent
kadam_adv_copy_campaign	将广告系列复制到某个广告系列组：克隆设置和出价，副本以暂停状态开始，并重新进入审核流程。可选切换定价模式、跨格式复制推送 <-> 页面内推送、复制自动规则和各网站出价	—
kadam_adv_bulk_replace_urls	在广告系列及其创意中查找并替换落地页 URL 片段。仅限管理员（模拟会话）；支持 dryRun	destructive
kadam_adv_set_campaign_rss	为原生广告系列指定 RSS 订阅源以导入创意，或通过空链接停止导入	idempotent
kadam_adv_set_easy_start	为广告系列启用或关闭 Easy Start（精选网站集）。仅限管理员（模拟会话）	idempotent
kadam_adv_get_blocked_traffic_sources	获取拒绝投放某广告系列的流量来源，按类别拦截和审核标签拦截分类。仅限管理员（模拟会话）	readOnly
kadam_adv_get_traffic_forecast	根据昨日竞价，获取某组定向的出价－流量曲线。曲线为空表示无法生成预测，并不代表流量为零	readOnly

出价管理

工具	说明	注释
kadam_adv_update_campaign_bid	更新单个广告系列的出价（轻量级，无需完整负载）。如果省略，则沿用当前国家/地区设置	幂等
kadam_adv_bulk_update_bids	一次性更新多个广告系列的出价（所有广告系列必须使用相同的定价模型）	幂等
kadam_adv_block_sites	停止或恢复广告系列中的网站（广告位）投放	—
kadam_adv_update_site_bids	设置单个网站（广告位）的出价：固定值（0.05）、倍数（x1.5）或移除（0）	幂等

广告系列文件夹

工具	说明	注释
kadam_adv_list_campaign_folders	列出文件夹及其广告系列数量和预算	只读
kadam_adv_get_campaign_folder	获取单个文件夹的信息：名称、归档状态和预算	只读
kadam_adv_create_campaign_folder	创建新文件夹（名称为 1-50 个字符）	—
kadam_adv_update_campaign_folder	部分更新：重命名和/或更改预算及分配	—
kadam_adv_set_campaign_folder_status	对逗号分隔的 ID 执行批量操作：启用/暂停广告系列、归档文件夹或恢复文件夹及其广告系列；返回每个文件夹的操作结果	幂等

创意

工具	描述	注解
kadam_adv_list_creatives	按广告系列、状态或搜索查询列出创意	只读
kadam_adv_create_creative	为广告系列创建创意：图片、HTML5 压缩包、iframe、HTML 标签、视频文件或 VAST 标签（需经过审核）	—
kadam_adv_update_creative	更新创意字段	—
kadam_adv_set_creative_status	批量更改创意状态：启用／暂停／归档／恢复；返回每个创意的处理结果	幂等
kadam_adv_get_creative_test_conversion	获取用于测试创意转化跟踪的签名链接（测试点击 + 框架预览）	—
kadam_adv_upload_bulk_images	为批量创意任务暂存图片（异步，返回一个任务）	—
kadam_adv_create_bulk_creatives	将暂存图片转为多个广告系列中的创意（异步，返回一个任务）	—
kadam_adv_get_bulk_job	批量任务状态：暂存图片、拒绝项、每行处理结果	—
kadam_adv_copy_creatives	将创意复制到其他广告系列（创意 × 目标广告系列数量份副本），原件不变	—
kadam_adv_move_creatives	将创意移至其他具有相同格式和定价模式的广告系列；创意会丢失各国家／地区出价，并重新进入审核	—
kadam_adv_get_creative_blocked_sources	拒绝某个创意的流量来源，按类别和审核标签分类。仅限经理使用（模拟身份会话）	—
kadam_adv_set_creative_bids	替换创意自身按国家设置的出价；未列出的国家／地区使用广告系列出价	—
kadam_adv_delete_creatives	通过逗号分隔的 ID 批量删除已归档的创意；需要 confirm: true，并报告每个 ID 的处理结果	破坏性操作

受众

工具	描述	注解
kadam_adv_list_audiences	列出受众，支持搜索和排序	readOnly
kadam_adv_get_audience	根据 ID 获取受众详细信息	readOnly
kadam_adv_create_audience	创建受众（pixel、code、fingerprint 或 S2S）	—
kadam_adv_update_audience	更新受众设置	—
kadam_adv_get_filtered_audience_sources	可用作筛选受众来源的受众。仅限 Manager（模拟会话）	—
kadam_adv_get_audience_params	pixel/S2S 受众会替换到其代码中的硬编码参数	—
kadam_adv_set_audience_params	替换 pixel/S2S 受众的硬编码参数	—
kadam_adv_delete_audience	永久删除受众（需要 confirm: true）	destructive

财务与统计

工具	描述	注解
kadam_adv_list_finance_operations	交易历史（存款、扣费、退款）	readOnly
kadam_adv_get_stats	统一统计 — 通过 reportType 参数提供 3 种报告类型：custom（使用维度/指标映射的报告构建器）、sites（按站点细分）、postbacks（转化日志）	readOnly

Publisher 工具（17 个）

需要 KADAM_PUB_API_KEY。

站点（来源）

工具	描述	注解
kadam_pub_list_sources	列出 Publisher 站点及其统计数据	readOnly
kadam_pub_create_source	添加新站点（启动验证流程）	—
kadam_pub_get_source	获取站点详细信息	readOnly
kadam_pub_update_source	更新站点名称	—
kadam_pub_set_source_status	更改站点状态（active/paused/archived/unarchived）	idempotent

广告单元

工具	描述	注解
kadam_pub_list_ad_units	列出站点的广告单元，按格式筛选（native/banner/push/popunder/inpagepush）	readOnly
kadam_pub_set_ad_unit_status	更改广告单元状态（active/paused/archived/restored）	idempotent

用户与统计信息

工具	描述	注释
kadam_pub_get_user_info	获取发布商账户信息和余额	readOnly
kadam_pub_get_stats	发布商统计信息，包含易读的维度／指标映射	readOnly

Kadam 智能变现

除了 Kadam 需求外，还通过外部广告网络销售广告单元的流量。API、代码和报告维度均将其称为普通的 mediation。请先阅读 kadam://reference/mediation；使用 groupBy=network 和 kadam_revenue / mediation_revenue 指标，在 kadam_pub_get_stats 中拆分收入。

工具	描述	注释
kadam_pub_list_mediation_networks	网络目录、已关联账户的网络，以及广告单元当前接入的网络	readOnly
kadam_pub_connect_mediation_network	将网络接入广告单元（自动解析账户和广告位）	—
kadam_pub_update_mediation_network	更改地理位置、唯一频次上限、代理策略、标签模板、广告位或账户	—
kadam_pub_set_mediation_network_status	将连接设为 active / paused	idempotent
kadam_pub_retest_mediation_network	重启强制测试流量占比（1-50%）；开始新的测量周期	—
kadam_pub_disconnect_mediation_network	移除连接（需要 confirm）	destructive
kadam_pub_update_mediation_network_account	轮换网络 API 密钥、重命名或停用账户	—
kadam_pub_delete_mediation_network_account	移除网络账户（需要 confirm）	destructive

资源（9）

Agent 在调用工具前可以读取的静态参考数据：

URI	描述
kadam://reference/campaign-types	所有广告格式类型及其 ID、功能、定价和创意素材规格
kadam://reference/pricing-models	CPC、CPM、CPV、CPA Target 的 ID 和描述
kadam://reference/creative-formats	各广告系列类型的创意素材要求
kadam://reference/ad-unit-types	发布商广告单元格式及其 ID
kadam://reference/site-states	发布商网站生命周期状态
kadam://reference/mediation	外部广告网络：账户、广告位、连接、测试流量占比、收入拆分
kadam://reference/report-dimensions	统计工具可用的维度和指标
kadam://reference/api-overview	Kadam API 功能概览

提示词（4 个）

预构建的工作流模板，引导 Agent 完成多步骤操作：

提示词	描述	参数
kadam_launch_campaign	分步创建广告系列（检查类型 -> 创建文件夹 -> 创建广告系列 -> 添加创意素材）	type、name、url、budget
kadam_campaign_performance	分析广告系列表现并提供优化建议	campaignId、period
kadam_optimize_sites	分析网站表现并建议调整黑名单/白名单	campaignId、minClicks、maxCPA
kadam_account_overview	完整的账户概览 — 广告系列、支出、表现最佳项	—

架构

src/
├── index.ts                  # Entry point, server instructions, transport
├── config.ts                 # Zod-validated env config with cache
├── errors.ts                 # AuthError class
├── logger.ts                 # Pino structured logging (stderr)
├── output-formatter.ts       # Text formatting + 50KB truncation
├── middleware/
│   └── tool-wrapper.ts       # Auth, error handling, logging middleware
├── api/
│   ├── http-client.ts        # Generic HTTP client with retry/429/timeout
│   ├── partners-client.ts    # Advertiser API (lazy singleton)
│   └── pub-client.ts         # Publisher API (lazy singleton)
├── utils/
│   ├── pagination.ts         # Shared pagination extraction
│   ├── cache-once.ts         # Generic async cache-once utility
│   └── dimension-mapper.ts   # Stats dimension name→ID resolution
├── types/
│   ├── common.ts             # Shared types (ApiListResponse, ReportConfig)
│   ├── advertiser.ts         # Campaign, Creative, Audience types + maps
│   ├── publisher.ts          # Source, AdUnit, PubUser types + maps
│   └── tool-module.ts        # ToolModule interface
├── tools/
│   ├── advertiser/           # 63 tools across 14 modules
│   └── publisher/            # 17 tools across 6 modules
├── resources/                # 9 reference resources
└── prompts/                  # 4 workflow prompts

关键设计决策

• ToolWrapper 中间件 — 为全部 80 个工具集中处理身份验证、错误格式化和日志记录
• 惰性单例 API 客户端 — 每个产品使用一个 HttpClient 实例，首次使用时创建
• 输出截断 — 每个响应硬性限制为 50KB，并通过 maxResults（默认 25，最大 100）防止大模型上下文溢出
• 易读输出 — 使用格式化表格、对齐的实体和分页元数据，而非原始 JSON
• 工具注释 — 使用 readOnlyHint、destructiveHint、idempotentHint 指导 Agent 行为
• 服务说明 — 连接时向大模型发送使用模式和限制条件
• 维度映射 — 统计工具接受易读名称（“clicks”、“spend”），并在内部将其解析为 API ID
• 按角色定制的目录 — bearer 原样转发，并在每个会话中通过 GET /access 读取一次其角色（参见“基于角色的目录”）。工具声明 requires: "impersonation"，ToolWrapper 会在客户端会话中跳过这些工具；campaigns.ts 仅在模拟身份下将仅限管理员使用的广告系列字段添加到其架构中。此处不实施任何权限控制 — API 仍会对客户端令牌返回 403 / 422 — 因此目录永远不会比密钥的实际权限范围更广；只有在无法访问 /access 时才会更窄

开发

先决条件

• Node.js >= 18
• npm

设置

git clone https://github.com/kadam-official/mcp-server.git
cd mcp-server
npm install
cp .env.example .env  # Fill in your API keys

命令

npm run dev             # Watch mode with tsx
npm run build           # Production build with Vite
npm run start           # Run built server
npm run typecheck       # TypeScript check
npm run lint            # ESLint
npm run format          # Prettier
npm test                # Run 82 tests
npm run test:coverage   # Tests with V8 coverage
npm run inspect         # MCP Inspector (visual debugger)

测试

使用 Vitest + MCP SDK InMemoryTransport，在 23 个文件中运行 202 项测试：

• 单元测试 — 输出格式化器、配置、HTTP 客户端（模拟 fetch）
• 中间件测试 — ToolWrapper 身份验证、错误格式化、日志记录
• 集成测试 — 通过内存 MCP 客户端测试包含全部 72 个工具、8 个资源和 4 个提示词的完整服务
• 工具处理程序测试 — 使用模拟 API 客户端测试每个工具模块

npm test
# Test Files  23 passed (23)
#      Tests  202 passed (202)

MCP Inspector

MCP Inspector 提供用于测试的可视化界面：

npm run build
npm run inspect

部署

Docker

docker build -t kadam-mcp-server .
docker run -i --rm -e KADAM_ADV_API_KEY=... kadam-mcp-server

CI/CD

.gitlab-ci.yml 流水线包括：

• lint — ESLint + TypeScript 检查
• test — 使用覆盖率运行 Vitest
• build — Vite 生产构建
• publish — npm 发布 + Docker 推送（手动触发）

许可证

MIT