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```bash
go install github.com/virgoC0der/go-mcp/cmd/oceanengine-mcp@latest
Or build from source:```bash
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```json
{
"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/oceanenginebackend 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```bash
make test # go test ./...
make vet # go vet ./...
make build # build the binary
```
License
MIT — see LICENSE.
