Kaminari Ad

@kaminari-ad/mcp

Kaminari Clickを手がけるチームが提供する、広告検証プラットフォームKaminari Adの公式Model Context Protocol（MCP）サーバーです。

AI エージェント（Cursor、Claude Desktop、Cline、およびMCP互換クライアント）が、APIキーを使ってKaminari Adのワークスペースに直接アクセスし、スキャンの開始、結果の確認、キャンペーンやポリシーの管理、アラートの閲覧を行えます。

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

Cursor

サーバーでできることや、各種クライアントの接続方法については、Kaminari Ad MCPの概要をご覧ください。

Claude Desktop

kaminari-ad-mcp.mcpbをダウンロード → ダブルクリックしてインストールします。Claude DesktopにAPIキーの設定フォームが表示されます。

Claude Code（CLI）

claude mcp add kaminari-ad -- npx -y @kaminari-ad/mcp
export KAMINARI_AD_API_KEY=your-key

インストールの詳細については、以下のクイックスタートをご覧ください。

---

クイックスタート

1. アカウントを登録してAPIキーを取得する

1. https://app.kaminari.ad/signupでアカウントを登録します（無料プランあり、カード登録不要）。
2. サインインしたら、Settings → API Keysに移動して新しいキーを生成するか、既存のAIアシスタント（一時ログインを使用）にcreate_api_keyツールを呼び出してもらいます。どちらの方法でも同じ結果が得られます。
3. キーが表示されるのは一度だけです。コピーしてください。キー全体は直ちにサーバー側でハッシュ化されます。

キーは不透明なランダム文字列で、必須のプレフィックスや固定長はありません。値全体をそのままのシークレットとして扱い、クライアント設定に一字一句そのまま貼り付けてください。

評価担当者／Anthropic Software Directoryのレビュー担当者向けのヒント：サンプルのスキャン、キャンペーン、アラートを用意したサンドボックステストアカウントについて、[email protected]からチームにお問い合わせください。

2a. ローカルインストール（stdioトランスポート）

MCPクライアントの設定に追加します（Cursor：~/.cursor/mcp.json、Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "kaminari-ad": {
      "command": "npx",
      "args": ["-y", "@kaminari-ad/mcp"],
      "env": {
        "KAMINARI_AD_API_KEY": "<your-kaminari-ad-api-key>",
      },
    },
  },
}

クライアントを再起動してください。MCPサーバーの一覧にkaminari-adが表示され、108個のツールが公開されます。

2b. ホスト型HTTPトランスポート（インストール不要）

クラウドエージェントやローカルのNodeランタイムがないクライアントでは、ホスト型エンドポイントを指定します。

{
  "mcpServers": {
    "kaminari-ad": {
      "url": "https://mcp.kaminari.ad/mcp",
      "headers": {
        "Authorization": "Bearer <your-kaminari-ad-api-key>",
      },
    },
  },
}

2c. OAuth 2.0（Claude ディレクトリ、サードパーティ製エージェント）

ホストされたサーバーは、RFC 9728 保護リソースメタデータを https://mcp.kaminari.ad/.well-known/oauth-protected-resource で公開し、Kaminari Ad 認可サーバー （https://app.kaminari.ad）を指定しています。/mcp への未認証リクエストには、 WWW-Authenticate: Bearer resource_metadata="…" ヘッダーが返されるため、 仕様に準拠した MCP クライアント（Claude.ai、Claude Code、サードパーティ製 エージェント）は、PKCE S256 と Dynamic Client Registration（RFC 7591）を使用した OAuth 2.0 認可コードフローを完了できます。

# Discovery — works without any credential
curl -sk https://mcp.kaminari.ad/.well-known/oauth-protected-resource

# Triggering the WWW-Authenticate hint
curl -isk https://mcp.kaminari.ad/mcp -X POST \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

CLI と単発のスクリプトには、引き続き API キーを推奨します — OAuth は、アプリごとの 同意とアプリごとの取り消しを必要とする対話型エージェント専用です。どちらの Bearer 形式も 同じ /mcp エンドポイントにアクセスします。サーバーはトークンをそのまま API に転送し、 API がどの種類の認証情報から発行されたかを判定します。

---

ツール

Kaminari Ad の公開 /api/v1 サーフェスをカバーする 109 個のツールです。各ツールには MCP の動作アノテーション（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付与されており、MCP クライアントは破壊的な操作の前に警告できます。ドメイン別の全一覧は次のとおりです。

• アカウント（14） — get_account、update_org、list_org_users、invite_user、update_user_role、remove_user、transfer_ownership、list_org_roles、create_custom_role、list_account_labels、update_account_labels、list_api_keys、create_api_key、revoke_api_key
• スキャン（13） — list_scans、get_scan、list_scan_children、create_scan、create_bulk_scans、recheck_scans、cancel_scan、get_scan_screenshot、get_scan_creative_screenshot、get_scan_landing_screenshot、get_scan_creative_html、get_scan_creative_video、get_scan_vast_xml
• キャンペーン（10） — list_campaigns、list_campaigns_picker、get_campaign、create_campaign、update_campaign、archive_campaign、unarchive_campaign、cancel_campaign、run_campaign、list_campaign_runs
• キャンペーングループ（10） — list/get/create/update/run/cancel/archive/unarchive + pause_campaign_group_schedule、resume_campaign_group_schedule
• 実行（3） — get_run、list_run_scans、cancel_run（キャンペーンの実行一覧を取得するには list_campaign_runs を使用してください。API には単独の /runs インデックスはありません）
• タグ（5） — list_tags、get_tag_definition、update_tag_definition、delete_tag_definition、list_scan_tags
• カスタムルール（7） — list_custom_rules、get_custom_rule、create_custom_rule、update_custom_rule、delete_custom_rule、test_custom_rule、test_custom_rules_batch
• カスタム分類体系（7） — list_custom_taxonomies、get_custom_taxonomy、create_custom_taxonomy、update_custom_taxonomy、delete_custom_taxonomy、restore_custom_taxonomy、parse_custom_taxonomy_text
• ポリシーセット（11） — list_policy_sets、get_policy_set、create_policy_set、update_policy_set、delete_policy_set、request_policy_set_approval、unpublish_policy_set、set_default_policy_set、list_policy_set_campaigns、attach_policy_set_campaigns、detach_policy_set_campaigns
• アラート（4） — list_alerts、update_alert_status、bulk_update_alert_status、get_alert_stats
• Webhook（11） — list_webhooks、get_webhook、create_webhook、update_webhook、delete_webhook、list_webhook_event_types、list_webhook_deliveries、test_webhook、rotate_webhook_secret、replay_webhook_delivery、bulk_replay_webhook
• 請求（4） — get_billing_summary、list_usage、get_usage_summary、list_balance_history
• 請求書（2） — list_invoices、get_invoice_pdf
• アラート通知（5） — list_alert_destinations、delete_alert_destination、set_alert_destination_version、get_campaign_alert_overrides、set_campaign_alert_overrides
• 参照データ（3） — list_geos、list_emulators、get_proxy_targeting

スクリーンショット（get_scan_screenshot、get_scan_creative_screenshot、get_scan_landing_screenshot）は、インラインの MCP image ブロックとして返されます。get_invoice_pdf と get_scan_creative_video はインラインのリソースブロックとして返されます。再取得も、事前署名 URL も不要です。2 つのテキストアーティファクト（get_scan_creative_html、get_scan_vast_xml）は、モデルが直接読み取れる文字列として返されます。ゲートウェイではすべてのアーティファクトのダウンロードサイズに上限を設けています。テキストアーティファクトは 256 KiB、バイナリアーティファクトは 8 MiB です。上限を超える場合は、いったんバッファーに格納してから拒否するのではなく、読み取り中に拒否します。

公開マーケティングフォームは公開していません（意図的です）。これらはエージェントの機能ではなく、kaminari.ad 自体への匿名の問い合わせ受付フォームです。

エージェント向けプロンプトの例

以下の3つのプロンプトは、それぞれ異なるツールの組み合わせを実行し、一般的なエージェントのワークフローを示します。

1. 「https://news.example.com/article-promo を、モバイルプロファイルで米国、英国、ドイツを対象にスキャンし、ペイウォールにリダイレクトされるものがあれば報告してください。」 list_emulators → create_bulk_scans → 待機 → list_scans（status=completed）→ get_scan → list_scan_tags を使用します。
2. 「brand-x.com のホームページを日本と米国から1時間ごとに再チェックするキャンペーンを作成し、マルウェアタグが表示されたら Slack で通知してください。」 list_emulators → list_policy_sets（malware を含むものを探す）→ create_campaign（schedule_enabled=true）→ attach_policy_set_campaigns → list_alert_destinations → set_campaign_alert_overrides（Slack の通知先を指定した mode: "override"）を使用します。
3. 「先月、広告検証にいくら使いましたか？また、どのキャンペーンが費用の原因になりましたか？」 get_usage_summary → list_usage（date_from/date_to を指定）→ scan_id ごとにグループ化 → get_scan → 費用の帰属確認に get_campaign を使用します。

機械可読なツール一覧全体はサーバー自体が提供します。任意の MCP クライアントで接続し、tools/list を呼び出してください。

---

セキュリティとテナントの分離

ホスト型 HTTP エンドポイントは、単一のプロセスから複数の組織にサービスを提供します。テナント間の分離を非常に重視しています。

• MCP サーバーは、厳密なステートレスのリクエスト単位パススルーです。Authorization ヘッダーをそのまま Kaminari Ad API に転送し、リクエスト間でテナントごとの状態を保存しません。
• キャッシュはなく、テナントに関連する情報でインデックス化されたインメモリデータもありません。
• HTTP モードでは、KAMINARI_AD_API_KEY 環境変数は起動時に拒否されます（stdio のみ）。デフォルトのフォールバックトークンはありません。
• セッション ID は、セッションを初期化した Bearer の SHA-256 にひも付けられます。異なる Bearer での再利用は拒否されます。
• Bearer がログに記録されることはありません。照合用に、ハッシュの先頭8文字のみを記録します。
• 上記の各ルールが CI の実行ごとに適用されることを確認する回帰テストについては、tests/isolation/ を参照してください。

セキュリティ上の問題を報告するには、SECURITY.md を参照してください。

---

開発

Docker を使う方法（ビルドにローカルの Node は不要ですが、ホスト側のコミットフックについては CONTRIBUTING を参照してください）。

make check           # lint + format-check + typecheck + arch-gates + test-cov
make test            # full test suite
make test-unit       # unit only
make test-isolation  # tenant-isolation suite

または、ホストに Node >=22.19.0 があれば、npm を直接使用できます（engines.node と一致します。.nvmrc では、CI と開発環境のマイナーバージョンをそろえるためのバージョンを固定しています）。[email protected] が node:worker_threads の markAsUncloneable を必要とするため（Node 22.19 以降）、パッケージでは 22.19.0 を厳密な下限としています。

npm ci --legacy-peer-deps
npm run lint && npm run typecheck && npm test

開発ワークフローとツールの追加方法については、CONTRIBUTING.md を参照してください。

メンテナーは、プライベート GitLab インスタンスで開発ゲート全体（統合テスト、デプロイ自動化、本番環境のスモークテスト）を実行し、リポジトリを GitHub にミラーリングしています。GitHub Actions 上の公開 CI（.github/workflows/ci.yml）では、コミュニティからのすべての PR に対して lint、型チェック、単体テスト、ビルド、バンドルサイズのチェックを実行します。そのため、コントリビューターは内部インフラへのアクセスなしに、合否をすばやく確認できます。タグのプッシュ（v*.*.*）によって .github/workflows/release.yml が起動し、OIDC の出所情報付きでパッケージを npm に公開し、GitHub Release を作成して、server.json を公式 MCP Registry に公開します。

---

安定性

このパッケージの公開インターフェースは次のとおりです。

1. CLI バイナリ kaminari-ad-mcp とその --transport stdio|http フラグ、.env.example に記載されている環境変数、終了コード（0 / 1 致命的エラー / 2 無効な設定）。
2. 登録されているすべてのツールが実装するMCP ワイヤープロトコル（ツール名、入力スキーマ、出力形式、アノテーション）。将来のメジャーバージョンで非推奨になるツールも、コンソール警告を表示したうえで、少なくとも1つのマイナーバージョンの間は引き続き動作します。

それ以外のすべて（dist/bin.d.ts からエクスポートされる TypeScript 型、深い階層からのインポート、内部クラスの構造）は公開契約の対象ではなく、どのリリースでも変更される可能性があります。このパッケージはライブラリではなく、CLI として扱ってください。

上記2項目について、セマンティックバージョニングに従います。各リリースの記録については、CHANGELOG.mdを参照してください。

---

プライバシー

• MCP サーバー自体が収集するデータ： 転送する Authorization ヘッダー以外にはありません。HTTP トランスポートはステートレスです。セッションは保存されず、各リクエストはそれぞれの Bearer を使って個別に認証されます。メモリ上に保持される状態は、sha256(bearer) をキーとするリーキーバケット型のレート制限器のみです。
• Kaminari Ad に転送されるデータ： すべてのツール呼び出しは、HTTPS 経由で /api/v1 に直接転送されます。Kaminari Ad のプライバシーポリシーが適用されます：https://kaminari.ad/privacy。
• ログ： 構造化された pino 出力で、HTTP モードでは JSON 形式です。Bearer トークン全体はマスキングされ、bearer_hash = sha256(token).slice(0,8) のみが、request_id、tool_name、api_status、elapsed_ms とともにログに記録されます。ツールの入力（顧客のスキャン ID や URL を含む場合があります）はログに記録されません。
• テレメトリー： ありません。OSS ビルドには NoopErrorReporter が含まれています。Sentry、OpenTelemetry エクスポーター、PostHog は同梱していません。

セキュリティまたはプライバシーに関する問題の報告については、SECURITY.mdを参照してください。

詳細情報

• Kaminari Ad MCP の概要 — エージェントがこのサーバーでできることと、各クライアントの設定方法。
• MCP サーバー開発者向けドキュメント — トランスポート、認証、OAuth 接続アプリ。
• REST API クイックスタート — すべてのツールが呼び出す /api/v1 インターフェース。
• 悪質な広告、自動リダイレクト、クローキングの検出 — スキャン結果で検出できる内容。
• 広告スタックにおける DarkSword：iOS エクスプロイトチェーン — Kaminari Ad チームによる調査。

ライセンス

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