Kadam Ad Network

@kadam-net/mcp-server

Kadam広告ネットワーク向けのMCP サーバーです。AI エージェントを通じて、キャンペーン、クリエイティブ、オーディエンス、サイト、分析を管理できます。

LLM を外部のツールやデータに接続するためのオープン標準であるModel Context Protocol（MCP）上に構築されています。

インストール（ワンクリック）

Cursor

または、.cursor/mcp.json に手動で追加します：

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

Claude Code

claude mcp add kadam -- npx -y @kadam-net/mcp-server

次に、環境変数を設定します：export KADAM_ADV_API_KEY=your-key

Claude Desktop

ダウンロード → ダブルクリック → インストールします。または、claude_desktop_config.json に手動で追加します（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

任意のMCP クライアント（一行で設定）

npx add-mcp @kadam-net/mcp-server

Docker

docker run -i --rm \
  -e KADAM_ADV_API_KEY=your-key \
  kadam/mcp-server:latest

npm グローバルインストール

npm install -g @kadam-net/mcp-server
KADAM_ADV_API_KEY=your-key kadam-mcp-server

設定

変数	必須	説明
KADAM_ADV_API_KEY	いずれか一つ	partners.kadam.net -> Profile -> API で取得する広告主 API キー
KADAM_PUB_API_KEY	いずれか一つ	pub.kadam.net -> Profile -> API で取得するパブリッシャー API キー
KADAM_ADV_API_BASE	いいえ	広告主 API の URL（デフォルト：https://partners.kadam.net/api/v1）
KADAM_PUB_API_BASE	いいえ	パブリッシャー API の URL（デフォルト：https://pub.kadam.net/api）
LOG_LEVEL	いいえ	ログレベル：trace、debug、info、warn、error、fatal（デフォルト：info）

stdio モードでは、少なくとも1つの API キーを指定する必要があります。HTTP モードでは、リクエストごとに Bearer 認証でトークンを渡します。

ロールベースのカタログ

ツールカタログには、ベアラーのロールが反映されます。セッションごとに1回（stdio モードではプロセスごとに1回）、サーバーは広告主 API の GET /api/v1/access を呼び出し、{ impersonation: bool } という応答を受け取ります。

ベアラー	impersonation	カタログ
広告主 API キー、または sub のみを含むキャビネット JWT	false	75 個のツール。create_campaign / update_campaign にマネージャー専用フィールドはありません
act.sub を含むキャビネット JWT（クライアントに代わって操作する Kadam マネージャー）	true	80 個のツール（以下の「マネージャー専用」の5つを追加）。キャンペーンの書き込みでは hasCorrectPostback、isDirectTrafficPriority、allowMultiAds を受け付けます
パブリッシャー API キー	n/a	パブリッシャー用ツール17個。パブリッシャー API にはインパーソネーション機能がありません

これはカタログのヒントであり、アクセス制御ではありません。Kadam API はすべての呼び出しで同じルールを適用します（クライアントトークンの場合は 403 / 422）。/access に接続できない場合、セッションにはクライアント用カタログが適用されます。常に小さいほうのカタログを表示すれば安全です。

HTTP トランスポート（マルチテナントデプロイ）

複数のユーザーにサービスを提供するサーバーサイドデプロイの場合：

変数	必須	説明
MCP_TRANSPORT	いいえ	"stdio"（デフォルト）または "http"
MCP_HTTP_PORT	いいえ	HTTP ポート（デフォルト：8080）
MCP_HTTP_HOST	いいえ	バインドアドレス（デフォルト：0.0.0.0）
KADAM_ADV_DOMAIN	いいえ	PRM 用の広告主ドメイン（デフォルト：https://partners.kadam.net）
KADAM_PUB_DOMAIN	いいえ	PRM 用のパブリッシャードメイン（デフォルト：https://pub.kadam.net）

docker run -d --name kadam-mcp \
  -e MCP_TRANSPORT=http \
  -p 8080:8080 \
  kadam/mcp-server:latest

HTTP 経由で接続する（Cursor / Claude）

{
  "mcpServers": {
    "kadam-adv": {
      "url": "https://partners.kadam.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADV_API_KEY"
      }
    }
  }
}

OAuth 経由で接続する（ChatGPT）

ChatGPT の設定で、サーバー URL として https://partners.kadam.net/mcp（広告主）または https://pub.kadam.net/mcp（パブリッシャー）を追加します。OAuth の検出、登録、ログインは自動的に行われます。

ツール（80）

広告主向けツール（63）

KADAM_ADV_API_KEY が必要です。

辞書

ツール	説明	注釈
kadam_adv_get_dictionary	キャンペーンタイプ、ブラウザー、プラットフォーム、デバイス、接続、カテゴリ、ISP、コンバージョンテンプレート、国、地域、都市の参照辞書	読み取り専用

キャンペーン

ツール	説明	注釈
kadam_adv_list_campaigns	フィルター（フォルダー、ステータス、種類、日付、検索）とページネーションを指定してキャンペーンを一覧表示します	readOnly
kadam_adv_get_campaign	ID を指定してキャンペーンの全設定を取得します。ランディングページ URL、国別入札額、予算、ターゲティング、フリークエンシーキャップ、スケジュール、コンバージョン設定が含まれます	readOnly
kadam_adv_create_campaign	ターゲティング（国、デバイス、OS、ブラウザー、年齢、性別、オーディエンス）をすべて指定してキャンペーンを作成します。dryRun: true の場合は検証のみを行います	—
kadam_adv_update_campaign	ID を指定してキャンペーンの任意のフィールドを更新します	—
kadam_adv_set_campaign_status	カンマ区切りの ID を指定してステータス（有効／一時停止／アーカイブ／復元）を一括変更し、ID ごとの結果を報告します	idempotent
kadam_adv_delete_campaigns	カンマ区切りの ID を指定してアーカイブ済みキャンペーンを一括削除します。confirm: true が必要で、ID ごとの結果を報告します	destructive
kadam_adv_move_campaigns	カンマ区切りのキャンペーン ID と移動先グループ ID を指定して、キャンペーンをキャンペーングループに移動します	idempotent
kadam_adv_copy_campaign	キャンペーンをキャンペーングループにコピーします。設定と入札額が複製され、コピーは一時停止状態で開始され、再審査を受けます。料金モデルの切り替え、push と in-page push 間のフォーマットをまたぐコピー、オートルール、サイトごとの入札額も指定できます	—
kadam_adv_bulk_replace_urls	キャンペーンとそのクリエイティブ全体で、ランディング URL の一部を検索して置換します。マネージャーのみ利用可能（偽装セッション）。dryRun に対応しています	destructive
kadam_adv_set_campaign_rss	RSS フィードをネイティブキャンペーンに設定してクリエイティブをインポートするか、リンクを空にしてインポートを停止します	idempotent
kadam_adv_set_easy_start	キャンペーンの Easy Start（厳選されたサイトセット）を有効または無効にします。マネージャーのみ利用可能（偽装セッション）	idempotent
kadam_adv_get_blocked_traffic_sources	キャンペーンを拒否しているトラフィックソースを、カテゴリブロックと審査タグブロックに分けて取得します。マネージャーのみ利用可能（偽装セッション）	readOnly
kadam_adv_get_traffic_forecast	前日のオークションに基づいて、指定したターゲティング条件の入札額とトラフィックの関係を取得します。カーブが空の場合、トラフィックがゼロという意味ではなく、予測を作成できなかったことを示します	readOnly

入札管理

ツール	説明	アノテーション
kadam_adv_update_campaign_bid	単一キャンペーンの入札額を更新します（軽量で、完全なペイロードは不要です）。省略した場合は現在の国が引き継がれます	冪等
kadam_adv_bulk_update_bids	複数のキャンペーンの入札額を一括更新します（すべて同じ価格モデルである必要があります）	冪等
kadam_adv_block_sites	キャンペーンでサイト（ゾーン）の買い付けを停止または再開します	—
kadam_adv_update_site_bids	サイト（ゾーン）ごとの入札額を設定します：固定値（0.05）、倍率（x1.5）、または削除（0）	冪等

キャンペーンフォルダー

ツール	説明	アノテーション
kadam_adv_list_campaign_folders	キャンペーン数と予算を含むフォルダーの一覧を取得します	読み取り専用
kadam_adv_get_campaign_folder	単一のフォルダーの名前、アーカイブ状態、予算を取得します	読み取り専用
kadam_adv_create_campaign_folder	新しいフォルダーを作成します（名前は1～50文字）	—
kadam_adv_update_campaign_folder	部分更新します：名前の変更、および／または予算と配分の変更	—
kadam_adv_set_campaign_folder_status	カンマ区切りのIDに対する一括操作です：キャンペーンの有効化／一時停止、キャンペーンを含むフォルダーのアーカイブまたは復元を行い、フォルダーごとの結果を返します	冪等

クリエイティブ

ツール	説明	注釈
kadam_adv_list_creatives	キャンペーン、ステータス、または検索クエリでクリエイティブを一覧表示します	readOnly
kadam_adv_create_creative	キャンペーン用のクリエイティブを作成します：画像、HTML5 アーカイブ、iframe、HTML タグ、動画ファイル、または VAST タグ（審査を経由します）	—
kadam_adv_update_creative	クリエイティブのフィールドを更新します	—
kadam_adv_set_creative_status	クリエイティブのステータスを一括変更します：有効／一時停止／アーカイブ済み／復元済み。クリエイティブごとの結果を返します	idempotent
kadam_adv_get_creative_test_conversion	クリエイティブのコンバージョントラッキングをテストする署名付きリンク（テストクリック＋フレームプレビュー）	—
kadam_adv_upload_bulk_images	クリエイティブの一括作成用に画像を準備します（非同期でジョブを返します）	—
kadam_adv_create_bulk_creatives	準備した画像から複数のキャンペーンのクリエイティブを一度に作成します（非同期でジョブを返します）	—
kadam_adv_get_bulk_job	一括処理の状態：準備済み画像、拒否、行ごとの結果	—
kadam_adv_copy_creatives	クリエイティブを他のキャンペーンにコピーします（クリエイティブ数 × コピー先数）。元のクリエイティブは変更されません	—
kadam_adv_move_creatives	同じフォーマットと料金モデルの別のキャンペーンにクリエイティブを移動します。地域別入札額は失われ、再審査となります	—
kadam_adv_get_creative_blocked_sources	クリエイティブが拒否されたトラフィックソースを、カテゴリと審査タグ別に表示します。マネージャーのみ（代理ログインセッション）	—
kadam_adv_set_creative_bids	クリエイティブ独自の国別入札額を置き換えます。指定されていない国ではキャンペーンの入札額が適用されます	—
kadam_adv_delete_creatives	アーカイブ済みクリエイティブをカンマ区切りの ID で一括削除します。confirm: true が必要で、ID ごとの結果を報告します	destructive

オーディエンス

ツール	説明	注釈
kadam_adv_list_audiences	検索と並べ替えを指定してオーディエンスを一覧表示します	readOnly
kadam_adv_get_audience	ID を指定してオーディエンスの詳細情報を取得します	readOnly
kadam_adv_create_audience	オーディエンスを作成します（ピクセル、コード、フィンガープリント、または S2S）	—
kadam_adv_update_audience	オーディエンスの設定を更新します	—
kadam_adv_get_filtered_audience_sources	フィルター済みオーディエンスのソースとして使用できるオーディエンスです。マネージャー専用（なりすましセッション）	—
kadam_adv_get_audience_params	ピクセル／S2S オーディエンスがコードに代入するハードコードされたパラメーターを取得します	—
kadam_adv_set_audience_params	ピクセル／S2S オーディエンスのハードコードされたパラメーターを置き換えます	—
kadam_adv_delete_audience	オーディエンスを完全に削除します（confirm: true が必要です）	destructive

財務と統計

ツール	説明	注釈
kadam_adv_list_finance_operations	取引履歴（入金、請求、返金）	readOnly
kadam_adv_get_stats	統合統計 — reportType パラメーターで 3 種類のレポートに対応します：custom（ディメンション／指標のマッピングを使ったレポートビルダー）、sites（サイト別の内訳）、postbacks（コンバージョンログ）	readOnly

パブリッシャー向けツール（17）

KADAM_PUB_API_KEY が必要です。

サイト（ソース）

ツール	説明	注釈
kadam_pub_list_sources	統計情報を含めてパブリッシャーのサイトを一覧表示します	readOnly
kadam_pub_create_source	新しいサイトを追加します（認証フローが開始されます）	—
kadam_pub_get_source	サイトの詳細情報を取得します	readOnly
kadam_pub_update_source	サイト名を更新します	—
kadam_pub_set_source_status	サイトのステータスを変更します（active/paused/archived/unarchived）	idempotent

広告ユニット

ツール	説明	注釈
kadam_pub_list_ad_units	サイトの広告ユニットを一覧表示します。フォーマットで絞り込めます（native/banner/push/popunder/inpagepush）	readOnly
kadam_pub_set_ad_unit_status	広告ユニットのステータスを変更します（active/paused/archived/restored）	idempotent

ユーザーと統計

ツール	説明	注釈
kadam_pub_get_user_info	パブリッシャーアカウント情報と残高を取得します	readOnly
kadam_pub_get_stats	人が読みやすいディメンション／指標の対応付けによるパブリッシャー統計	readOnly

Kadam スマートメディエーション

Kadam の需要と並行して、広告ユニットのトラフィックを外部広告ネットワークで販売します。API、 コード、レポートのディメンションでは、これを単に mediation と呼びます。まず kadam://reference/mediation を読み、groupBy=network と kadam_revenue ／ mediation_revenue 指標を指定して、kadam_pub_get_stats で収益を分割してください。

ツール	説明	注釈
kadam_pub_list_mediation_networks	アカウントを持つネットワークの一覧と、広告ユニットで現在稼働しているネットワークを表示します	readOnly
kadam_pub_connect_mediation_network	ネットワークを広告ユニットに接続します（アカウントとプレースメントは自動で解決されます）	—
kadam_pub_update_mediation_network	地域、ユニーク上限、プロキシポリシー、タグテンプレート、プレースメント、またはアカウントを変更します	—
kadam_pub_set_mediation_network_status	接続を有効／一時停止に設定します	idempotent
kadam_pub_retest_mediation_network	強制テスト配信（1～50％）を再開します（新しい測定期間が始まります）	—
kadam_pub_disconnect_mediation_network	接続を削除します（confirm が必要です）	destructive
kadam_pub_update_mediation_network_account	ネットワーク API キーを更新するか、アカウント名を変更または無効化します	—
kadam_pub_delete_mediation_network_account	ネットワークアカウントを削除します（confirm が必要です）	destructive

リソース（9）

エージェントがツールを呼び出す前に読み取れる静的なリファレンスデータです。

URI	説明
kadam://reference/campaign-types	ID、機能、価格、クリエイティブ仕様を含む、すべての広告フォーマットタイプ
kadam://reference/pricing-models	ID と説明を含む CPC、CPM、CPV、CPA Target
kadam://reference/creative-formats	キャンペーンタイプごとのクリエイティブ要件
kadam://reference/ad-unit-types	ID を含むパブリッシャー広告ユニットのフォーマット
kadam://reference/site-states	パブリッシャーサイトのライフサイクル状態
kadam://reference/mediation	外部広告ネットワーク：アカウント、プレースメント、接続、テスト配信、収益分割
kadam://reference/report-dimensions	統計ツールで利用できるディメンションと指標
kadam://reference/api-overview	Kadam API の機能概要

プロンプト（4）

エージェントを複数ステップの操作に導く、事前構築済みのワークフローテンプレートです。

プロンプト	説明	引数
kadam_launch_campaign	キャンペーン作成の手順（種類の確認 → フォルダーの作成 → キャンペーンの作成 → クリエイティブの追加）	type、name、url、budget
kadam_campaign_performance	最適化の提案を含むキャンペーンのパフォーマンス分析	campaignId、period
kadam_optimize_sites	サイトのパフォーマンスを分析し、ブラックリスト／ホワイトリストの変更を提案します	campaignId、minClicks、maxCPA
kadam_account_overview	アカウント全体の概要 — キャンペーン、費用、上位の実績	—

アーキテクチャ

src/
├── index.ts                  # Entry point, server instructions, transport
├── config.ts                 # Zod-validated env config with cache
├── errors.ts                 # AuthError class
├── logger.ts                 # Pino structured logging (stderr)
├── output-formatter.ts       # Text formatting + 50KB truncation
├── middleware/
│   └── tool-wrapper.ts       # Auth, error handling, logging middleware
├── api/
│   ├── http-client.ts        # Generic HTTP client with retry/429/timeout
│   ├── partners-client.ts    # Advertiser API (lazy singleton)
│   └── pub-client.ts         # Publisher API (lazy singleton)
├── utils/
│   ├── pagination.ts         # Shared pagination extraction
│   ├── cache-once.ts         # Generic async cache-once utility
│   └── dimension-mapper.ts   # Stats dimension name→ID resolution
├── types/
│   ├── common.ts             # Shared types (ApiListResponse, ReportConfig)
│   ├── advertiser.ts         # Campaign, Creative, Audience types + maps
│   ├── publisher.ts          # Source, AdUnit, PubUser types + maps
│   └── tool-module.ts        # ToolModule interface
├── tools/
│   ├── advertiser/           # 63 tools across 14 modules
│   └── publisher/            # 17 tools across 6 modules
├── resources/                # 9 reference resources
└── prompts/                  # 4 workflow prompts

主な設計上の判断

• ToolWrapper ミドルウェア — 80 個すべてのツールに対する認証検証、エラー形式の統一、ロギングを一元化します
• 遅延初期化されるシングルトン API クライアント — 製品ごとに HttpClient インスタンスを 1 つ用意し、初回使用時に作成します
• 出力の切り詰め — LLM のコンテキストあふれを防ぐため、maxResults（デフォルトは 25、最大は 100）を使い、レスポンスごとに 50KB の上限を設けます
• 人が読みやすい出力 — 生の JSON ではなく、書式設定された表、整列されたエンティティ、ページネーションのメタデータを出力します
• ツールのアノテーション — readOnlyHint、destructiveHint、idempotentHint により、エージェントの動作をガイドします
• サーバーの指示 — 接続時に、使用パターンと制約を LLM に送信します
• ディメンションのマッピング — 統計ツールは人が読みやすい名前（「クリック数」、「費用」）を受け取り、内部で API ID に解決します
• ロールに応じたカタログ — ベアラートークンは変更せずに転送され、そのロールは各セッションで GET /access から一度だけ読み取られます（「ロールベースのカタログ」を参照）。ツールは requires: "impersonation" を宣言し、ToolWrapper はクライアントセッションではそれらをスキップします。campaigns.ts は、インパーソネーション時にのみ、マネージャー専用のキャンペーンフィールドをスキーマに追加します。ここでは何も強制されません。API はクライアントトークンに対しても引き続き 403／422 を返すため、カタログがキーの実際の権限より広くなることはありません。/access に到達できない場合に、狭くなるだけです

開発

前提条件

• Node.js >= 18
• npm

セットアップ

git clone https://github.com/kadam-official/mcp-server.git
cd mcp-server
npm install
cp .env.example .env  # Fill in your API keys

コマンド

npm run dev             # Watch mode with tsx
npm run build           # Production build with Vite
npm run start           # Run built server
npm run typecheck       # TypeScript check
npm run lint            # ESLint
npm run format          # Prettier
npm test                # Run 82 tests
npm run test:coverage   # Tests with V8 coverage
npm run inspect         # MCP Inspector (visual debugger)

テスト

Vitest + MCP SDK InMemoryTransport を使用した、23 ファイルにわたる 202 件のテストです。

• ユニットテスト — 出力フォーマッター、設定、HTTP クライアント（fetch をモック）
• ミドルウェアテスト — ToolWrapper の認証、エラー形式の統一、ロギング
• 統合テスト — インメモリの MCP クライアントを介して、72 個すべてのツール、8 個のリソース、4 個のプロンプトを備えたサーバー全体をテストします
• ツールハンドラーのテスト — モック API クライアントを使用した各ツールモジュールのテスト

npm test
# Test Files  23 passed (23)
#      Tests  202 passed (202)

MCP Inspector

MCP Inspector は、テスト用のビジュアルインターフェースを提供します。

npm run build
npm run inspect

デプロイ

Docker

docker build -t kadam-mcp-server .
docker run -i --rm -e KADAM_ADV_API_KEY=... kadam-mcp-server

CI/CD

.gitlab-ci.yml パイプラインには、次の処理が含まれます。

• lint — ESLint + TypeScript チェック
• test — カバレッジ付きの Vitest
• build — Vite の本番ビルド
• publish — npm publish + Docker push（手動トリガー）

ライセンス

MIT