Go-MCP

oceanengine-mcp

Ocean Engine（巨量引擎） — ByteDance の国内広告プラットフォーム（巨量广告 / 巨量千川 / 本地推 / 星图）向けの Model Context Protocol（MCP）サーバーです。AI エージェントが標準 MCP インターフェースを介して広告主アカウント、キャンペーン、広告、パフォーマンスレポートを照会できます。また、明示的に有効化すると、キャンペーンのステータスや予算を調整できます。

このプロジェクトの背景。 「汎用 Go MCP SDK はどれか」という問いには、答えが出ています。Google とともにメンテナンスされている公式の modelcontextprotocol/go-sdkと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

設定

サーバーは環境変数で設定します。

認証 — 次の 2 つのモードから選択します。

静的トークン（トークンの更新はご自身で管理します）：

変数	説明
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" }
    }
  }
}

ツール

読み取りツール（常に利用可能）：

ツール	Ocean Engine エンドポイント	目的
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 が設定されている場合のみ利用可能。アカウントに変更を加えます）：

ツール	Ocean Engine エンドポイント	目的
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)

Ocean Engine クライアントは、意図的に薄く、依存関係を最小限に抑えています。後からエンドポイントの対応範囲を広げる場合は、MCP ツール層に手を加えることなく、そのメソッドの実装に、はるかに大規模なコミュニティ SDK bububa/oceanengine を利用できます。

ロードマップ

• OAuth トークンの更新 ✅ 完了（トークンソースを自動更新）
• 千川（Qianchuan）の EC 広告エンドポイント
• レポートのディメンション／指標の拡充と非同期レポートのエクスポート
• すべてのエンドポイントに対応するための、オプションの bububa/oceanengine バックエンド

リポジトリ名について

このプロジェクトは、歴史的な経緯から現在 go-mcp リポジトリに置かれています。 本来は専用の oceanengine-mcp リポジトリに置くことを想定しています。リポジトリ名を変更すると、スターと履歴を維持したまま、インポートパスもそれに合わせて更新されます。

開発

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

ライセンス

MIT — LICENSE を参照してください。