Go-MCP

oceanengine-mcp

A Model Context Protocol (MCP) server for Ocean Engine (巨量引擎) — ByteDance's domestic advertising platform (巨量广告 / 巨量千川 / 本地推 / 星图). It lets AI agents query advertiser accounts, campaigns, ads and performance reports — and, when explicitly enabled, adjust campaign status and budget — over the standard MCP interface.

Why this exists. The "general-purpose Go MCP SDK" question is settled: the official modelcontextprotocol/go-sdk (maintained with Google) and mark3labs/mcp-go own that space. The open niche is vertical MCP servers. Google Ads and Meta Ads already have MCP servers (and TikTok Ads has several), but Ocean Engine — the domestic Chinese platform — has none. This project fills that gap, and is built on top of the official SDK rather than reimplementing the protocol.

Status

Early but functional. The MCP layer is fully working (verified end-to-end via the in-memory transport and a stdio smoke test); the Ocean Engine client implements the documented Marketing API endpoints. Hitting the live API requires a valid access_token from the Ocean Engine open platform.

Install

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

Or build from source:

make build   # produces ./bin/oceanengine-mcp

Configuration

The server is configured via environment variables.

Authentication — choose one of two modes:

Static token (you manage refresh yourself):

Variable	Description
OCEANENGINE_ACCESS_TOKEN	OAuth access token from the Ocean Engine open platform

Auto-refresh (recommended — access tokens last ~1 day): supply app credentials and a refresh token and the server refreshes transparently before expiry. Ocean Engine rotates the refresh token on every refresh, so the server tracks the latest one in memory for its lifetime.

Variable	Required	Description
OCEANENGINE_APP_ID	yes	developer app ID (numeric)
OCEANENGINE_APP_SECRET	yes	developer app secret
OCEANENGINE_REFRESH_TOKEN	yes	OAuth refresh token (valid ~30 days)
OCEANENGINE_ACCESS_TOKEN	no	current access token, if you have a fresh one
OCEANENGINE_ACCESS_TOKEN_EXPIRES_IN	no	remaining lifetime in seconds; omit to refresh on first use

Auto-refresh mode activates when OCEANENGINE_APP_ID, OCEANENGINE_APP_SECRET and OCEANENGINE_REFRESH_TOKEN are all set; otherwise the server falls back to the static OCEANENGINE_ACCESS_TOKEN.

Persisting the rotated refresh token across restarts: when embedding the package, pass oceanengine.WithOnRefresh(...) to NewRefreshingTokenSource to receive each new token pair and store it.

Other options:

Variable	Required	Description
OCEANENGINE_BASE_URL	no	API host override (defaults to https://api.oceanengine.com)
OCEANENGINE_ENABLE_WRITES	no	set to 1/true to register the mutating tools (off by default)

Use with an MCP client

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

Tools

Read tools (always available):

Tool	Ocean Engine endpoint	Purpose
oceanengine_get_advertiser_info	GET /2/advertiser/info/	account info by advertiser ID
oceanengine_list_campaigns	GET /2/campaign/get/	list campaigns (广告组), paginated
oceanengine_list_ads	GET /2/ad/get/	list ads (广告计划), paginated
oceanengine_get_report	GET /2/report/ad/get/	performance report by date range/dimensions

Write tools (only when OCEANENGINE_ENABLE_WRITES is set — they mutate the live account):

Tool	Ocean Engine endpoint	Purpose
oceanengine_update_campaign_status	POST /2/campaign/update/status/	enable / disable / delete campaigns
oceanengine_update_campaign_budget	POST /2/campaign/update/budget/	set a campaign budget

Architecture

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)

The Ocean Engine client is deliberately thin and dependency-light. To broaden endpoint coverage later, its methods can be backed by the much larger community SDK bububa/oceanengine without touching the MCP tool layer.

Roadmap

• OAuth token refresh ✅ done (auto-refresh token source)
• 千川 (Qianchuan) e-commerce ad endpoints
• Broader report dimensions/metrics and async report export
• Optional bububa/oceanengine backend for full endpoint coverage

Note on the repository name

This project currently lives in the go-mcp repository for historical reasons. The intended home is a dedicated oceanengine-mcp repository — renaming the repo (which preserves stars and history) updates the import path accordingly.

Development

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

License

MIT — see LICENSE.