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](https://github.com/modelcontextprotocol/go-sdk)

(maintained with Google) and [mark3labs/mcp-go](https://github.com/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):

*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.

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:

Use with an MCP client

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

Tools

Read tools (always available):

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

account):

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](https://github.com/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.