Go-MCP

oceanengine-mcp

一个用于 Ocean Engine（巨量引擎） 的 Model Context Protocol（MCP）服务。Ocean Engine 是字节跳动旗下的国内广告平台（巨量广告 / 巨量千川 / 本地推 / 星图）。它支持 AI Agent 通过标准 MCP 接口查询广告主账户、广告系列、广告和效果报告；明确启用后，还可调整广告系列状态和预算。

项目缘由。“通用 Go MCP SDK”的问题已有定论：官方 modelcontextprotocol/go-sdk（与 Google 共同维护）和 mark3labs/mcp-go 已占据这一领域。尚未覆盖的细分领域是垂直领域 MCP 服务。Google Ads 和 Meta Ads 已有 MCP 服务（TikTok Ads 也有好几个），但**国内平台 Ocean Engine 还没有。**本项目填补了这一空白，并构建在官方 SDK 之上，而不是重新实现该协议。

状态

目前处于早期阶段，但已能正常使用。MCP 层已完全可用（已通过内存传输和 stdio 冒烟测试完成端到端验证）；Ocean Engine 客户端实现了文档中所述的 Marketing API 端点。访问线上 API 需要从 Ocean Engine 开放平台 获取有效的 access_token。

安装

go install github.com/virgoC0der/go-mcp/cmd/oceanengine-mcp@latest

或从源代码构建：

make build   # produces ./bin/oceanengine-mcp

配置

服务通过环境变量进行配置。

身份验证——选择以下两种模式之一：

静态令牌（自行管理刷新）：

变量	说明
OCEANENGINE_ACCESS_TOKEN	从 Ocean Engine 开放平台获取的 OAuth 访问令牌

自动刷新（推荐——访问令牌有效期约为 1 天）：提供应用凭据和刷新令牌，服务会在访问令牌过期前自动刷新。Ocean Engine 每次刷新都会轮换刷新令牌，因此服务会在其运行期间于内存中跟踪最新令牌。

变量	必填	说明
OCEANENGINE_APP_ID	是	开发者应用 ID（数字）
OCEANENGINE_APP_SECRET	是	开发者应用密钥
OCEANENGINE_REFRESH_TOKEN	是	OAuth 刷新令牌（有效期约为 30 天）
OCEANENGINE_ACCESS_TOKEN	否	当前访问令牌（如有新令牌）
OCEANENGINE_ACCESS_TOKEN_EXPIRES_IN	否	剩余有效时间（秒）；省略时会在首次使用时刷新

当 OCEANENGINE_APP_ID、OCEANENGINE_APP_SECRET 和 OCEANENGINE_REFRESH_TOKEN 均已设置时，将启用自动刷新模式；否则服务将回退到静态 OCEANENGINE_ACCESS_TOKEN。

在重启后保留轮换后的刷新令牌：嵌入该软件包时，将 oceanengine.WithOnRefresh(...) 传递给 NewRefreshingTokenSource，以接收每一对新令牌并进行存储。

其他选项：

变量	必填	说明
OCEANENGINE_BASE_URL	否	API 主机覆盖值（默认为 https://api.oceanengine.com）
OCEANENGINE_ENABLE_WRITES	否	设置为 1/true 以注册可更改数据的工具（默认关闭）

与 MCP 客户端配合使用

{
  "mcpServers": {
    "oceanengine": {
      "command": "oceanengine-mcp",
      "env": { "OCEANENGINE_ACCESS_TOKEN": "your-token" }
    }
  }
}

工具

读取工具（始终可用）：

工具	巨量引擎端点	用途
oceanengine_get_advertiser_info	GET /2/advertiser/info/	根据广告主 ID 获取账户信息
oceanengine_list_campaigns	GET /2/campaign/get/	分页列出广告组
oceanengine_list_ads	GET /2/ad/get/	分页列出广告计划
oceanengine_get_report	GET /2/report/ad/get/	按日期范围和维度获取效果报告

写入工具（仅在设置 OCEANENGINE_ENABLE_WRITES 时可用——会修改实时账户）：

工具	巨量引擎端点	用途
oceanengine_update_campaign_status	POST /2/campaign/update/status/	启用 / 停用 / 删除广告组
oceanengine_update_campaign_budget	POST /2/campaign/update/budget/	设置广告组预算

架构

cmd/oceanengine-mcp     entrypoint: reads env, runs MCP over stdio
internal/mcpserver      registers tools on the official go-sdk; no protocol code
internal/oceanengine    thin Marketing API client (auth, envelope, endpoints)

巨量引擎客户端刻意保持精简，依赖也尽可能少。若要在之后扩展端点覆盖范围，可以使用规模大得多的社区 SDK bububa/oceanengine 为其方法提供支持，而无需改动 MCP 工具层。

路线图

• OAuth 令牌刷新 ✅ 已完成（自动刷新令牌来源）
• 千川电商广告端点
• 扩展报告维度 / 指标并支持异步报告导出
• 可选的 bububa/oceanengine 后端，以覆盖全部端点

关于仓库名称的说明

由于历史原因，本项目目前位于 go-mcp 仓库中。项目计划迁移至专用的 oceanengine-mcp 仓库——重命名仓库（会保留星标和历史记录）即可相应更新导入路径。

开发

make test    # go test ./...
make vet     # go vet ./...
make build   # build the binary

许可证

MIT — 参见 LICENSE。