CreatorDB

creatordb-mcp-server

Model Context Protocol サーバーです。CreatorDB V3 API を、MCP 対応クライアント（Claude Code、Claude Desktop、Cursor など）に公開します。

6つの領域にわたる43個のツール：

• クリエイター側のデータ — YouTube、Instagram、TikTok のプロフィール、パフォーマンス、オーディエンスのデモグラフィック、連絡先、コンテンツ詳細、パフォーマンス履歴
• クリエイター検索 — 3つすべてのプラットフォームを対象とした自然言語検索に加え、プラットフォームごとの構造化フィルター検索（国、言語、フォロワー数のしきい値、ニッチ、ハッシュタグ、オーディエンスのデモグラフィックなど）
• ブランド側／スポンサーインテリジェンス (YouTube + Instagram のみ — TikTok のブランドデータはインデックス化されていません) — CreatorDB がインデックス化した10K以上のブランドを検索し、ブランドの完全なプロフィールを取得し、ブランドがスポンサーになったクリエイターをすべて一覧表示し、スポンサー対象クリエイター全体のオーディエンスのデモグラフィックを集計して取得し、プラットフォームを横断した支出／CPM／CPE の集計データを取得します。負荷の大きいスポンサー関連の読み取り操作（get_sponsor_creators、get_sponsor_performance、get_sponsor_audience、get_sponsor_summary）は、それぞれ15クレジットを消費します。計画的に使用してください。get_sponsor_information は2クレジット、search_sponsors は2クレジット、list_sponsors は1クレジットを消費します。
• コンテンツ検索 — コンテンツレベルのフィルター（公開期間、再生数／いいね数のしきい値、ハッシュタグ、言語など）で個々の TikTok 動画を検索します。クリエイター検索とは異なり、チャンネルではなく投稿を返します。(YouTube と Instagram のコンテンツ検索は、クレジット消費を抑えるための最適化中につき、一時的に利用できません。TikTok は引き続き利用できます。)
• トピックおよびニッチの分類体系 — プロフィールのレスポンスで返されるクリエイターごとのトピック／ニッチ ID を解決するための、ページ分割された検索可能なカタログ（YT トピック約470件、YT ニッチ約16K件、IG／TT はそれぞれ約40K件）。ページを移動する代わりに、search を指定してフレーズから項目名を検索できます。
• アカウント — エンドポイント別、プラットフォーム別に分類されたクレジット使用量。

すべてのツールは、基盤となる V3 JSON と Credits used: N | Remaining: M のフッター行を返すため、AI はクレジットの使用量を正確に把握できます。

Claude Code をお使いですか？ Claude Code でこの README を開く（または URL を Claude セッションに貼り付ける）と、「この MCP をセットアップして」と指示できます。以下の手順は、AI アシスタントが上から順に実行できるように記載されています。

クイックスタート

クライアントに応じて、接続方法は2通りあります。

• ローカルクライアント（Claude Code、Claude Desktop、Cursor）では、npx を使ってサーバーをサブプロセスとして実行します。インストール（ローカル／stdio）を参照してください。
• ウェブ／デスクトップ／モバイルクライアントでは、ホストされたエンドポイントに接続するか、Claude のコネクターディレクトリから CreatorDB を直接追加します。リモートコネクターを参照してください。

どちらの方法でも同じ43個のツールを利用できます。どちらも CreatorDB V3 API キーが必要です。

1. 前提条件
   • ローカルで実行する場合：Node.js 22 以降（node -v で確認）
   • CreatorDB V3 API キー — https://creatordb.app のアカウント設定から取得するか、チーム管理者にお問い合わせください
2. 以下から接続方法を選択
3. 新しいツールを読み込むため、MCP クライアントを再起動
4. Claude Code で /mcp を実行して確認します。creatordb がステータス connected で表示されるはずです。

インストール（ローカル／stdio）

Claude Code、Claude Desktop、Cursor 向けです。サーバーは1つの環境変数 CREATORDB_API_KEY（V3 キー）を読み取ります。

方法 A — npm から npx（推奨）

パッケージは npm に @creatordbai/mcp-server として公開されています。ローカルへのクローン、SSH キー、GitHub へのアクセスは不要です。

Claude Code:

claude mcp add creatordb -s user \
  -e CREATORDB_API_KEY=YOUR_CREATORDB_API_KEY \
  -- npx -y @creatordbai/mcp-server

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "creatordb": {
      "command": "npx",
      "args": ["-y", "@creatordbai/mcp-server"],
      "env": { "CREATORDB_API_KEY": "YOUR_CREATORDB_API_KEY" }
    }
  }
}

GitHub 組織へのアクセス権があり、npm のリリースではなく main を追跡したい場合は、npm パッケージ名を git+ssh://[email protected]/CreatorDB/creatordb-mcp-server.git に置き換えてください。リポジトリの prepare スクリプトがインストール時にビルドします。

方法 B — ローカルでクローンしてビルドする

ソースを確認・変更したい場合や、お使いの環境で git 経由の npx が動作しない場合に適しています。

git clone https://github.com/CreatorDB/creatordb-mcp-server.git
cd creatordb-mcp-server
npm install
npm run build

# Then register with Claude Code:
claude mcp add creatordb -s user \
  -e CREATORDB_API_KEY=YOUR_CREATORDB_API_KEY \
  -- node "$(pwd)/dist/index.js"

Claude Desktop では、方法 A と同じ JSON を使い、command と args を入れ替えます。

"command": "node",
"args": ["/absolute/path/to/creatordb-mcp-server/dist/index.js"],

方法 C — プロジェクト単位で設定する .mcp.json（チームに最適）

CreatorDB プロジェクトのリポジトリに .mcp.json を配置します。そのリポジトリを Claude Code で開いた人は誰でも、MCP を有効にするよう求められます。各自がセットアップコマンドを実行する必要はありません。

{
  "mcpServers": {
    "creatordb": {
      "command": "npx",
      "args": ["-y", "git+ssh://[email protected]/CreatorDB/creatordb-mcp-server.git"],
      "env": { "CREATORDB_API_KEY": "${CREATORDB_API_KEY}" }
    }
  }
}

${CREATORDB_API_KEY} はユーザーのシェル環境から読み取られるため、キーが git に含まれることはありません。各チームメンバーは .zshrc／.bash_profile で一度設定します。

export CREATORDB_API_KEY=YOUR_CREATORDB_API_KEY

リモートコネクター（Claude のウェブ版、デスクトップ、モバイル）

ローカルのサブプロセスを起動できない Claude クライアントは、npx を実行する代わりに、ホストされたエンドポイントに接続します。接続方法は 2 つあります。

コネクターディレクトリから追加する（最も簡単）。 CreatorDB は Claude のコネクターディレクトリに掲載されています。Claude で 設定 → コネクター → 追加 → コネクターを参照 を開き、CreatorDB を検索して CreatorDB MCP を開き、Claude に接続 をクリックします。

手動で追加する。 直接追加することもできます。設定 → コネクター → 追加 → カスタムコネクターを追加 を開き、次の URL を入力します。

https://mcp.creatordb.app/mcp

Advanced OAuth Client ID／Secret のフィールドは空欄のままにしてください。サーバーがクライアントを自動的に登録します。

どちらの方法でも、接続時に CreatorDB API キーの入力を求められ、同じ 43 個のツールが表示されます。

注意：

• 接続時にキーの入力を求められます。コネクターはキーを暗号化されたセッショントークンに封入し、別途コピーを保持しません。CreatorDB がキーを保持するのは、発行した認証情報としてのみです。
• エンドポイントを直接呼び出すプログラムクライアントは、代わりに Authorization: Bearer <your CreatorDB V3 API key> を送信できます。
• ヘルスチェック：https://mcp.creatordb.app/health（認証不要、クレジット消費なし）— サービスが稼働中の場合、{"status":"ok",...} を返します。
• asia-northeast1 の Firebase Cloud Function（gen 2）としてホストされています。ソースは functions/ にあります。
• キーをお持ちでない場合は、https://app.creatordb.app で取得するか、[email protected] までメールでお問い合わせください。

API キーの変更

MCP サーバー内でキーを更新することはできません。キーは保存されていません。クライアントの MCP 設定を変更して、再起動してください。

ローカルインストール（Claude Code、Claude Desktop、Cursor）

セットアップ時に使用した設定ファイルを編集します。

• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Cursor： ~/.cursor/mcp.json（またはアプリ内の MCP 設定 UI）
• Claude Code： ~/.mcp.json またはプロジェクトの .mcp.json

CREATORDB_API_KEY の値を変更した後、クライアントを完全に再起動してください（Claude Desktop の場合は ⌘Q で終了して再度開き、Cursor の場合はアプリを再起動するなど）。MCP クライアントがキーを読み取るのは、プロセスの起動時のみです。

シェル環境からキーを設定している場合（上記の方法 C のように ${CREATORDB_API_KEY} 構文を使用）、~/.zshrc／.bash_profile を更新し、クライアントを再起動する前にターミナルを再起動してください。

リモートコネクター（Claude のウェブ版、デスクトップ、モバイル）

設定 → コネクター → CreatorDB で接続を解除してから再接続し、求められたら新しいキーを入力します。（Bearer トークンを送信するプログラムクライアントは、新しいキーを送信し始めるだけです。）

漏えいしたキーをローテーションする際の注意点

クライアント側でキーを変更しても、ツールの認証に使われるキーが切り替わるだけです。以前のキーが無効になるわけではありません。 古いキーが漏えいしたためにローテーションする場合は、次の手順を実行してください。

1. CreatorDB アカウントに移動し、そこで古いキーを失効させます。これにより、V3 API 層で実際にキーが無効になります。
2. 上記の手順に従って、新しいキーを使用するよう MCP クライアントを更新します。

MCP サーバーは単一のリクエストを超えてキーを保持しないため、サーバー側で消去が必要な「保存済みのキー」はありません。

動作確認

インストール後、Claude Code（または MCP クライアント）を再起動して、次の手順を実行します。

1. /mcp を実行します。ステータスが connected の creatordb が表示されます。
2. ツールを使う質問を Claude にします。例：「creatordb を使って、MrBeast の YouTube プロフィールを調べてください（channelId UCX6OQ3DkcsbYNE6H8uQQuVA）」
3. 応答にクリエイターデータと Credits used: 2 | Remaining: … のフッターが含まれていることを確認します。

トラブルシューティング

症状	原因	対処方法
/mcp で creatordb が failed と表示される、または connecting のままになる	API キーが設定されていないか、間違っています	正しいキーを使って claude mcp remove creatordb && claude mcp add … で再登録します
ツールは動作するものの、すべての応答の末尾に Credits used: undefined と表示される	このサーバーの古いビルドのツールスキーマが残っています	MCP クライアントを再起動します。クライアントはセッション開始時にスキーマをキャッシュします
Instagram ツールで Error: VALIDATION_ERROR が発生する	uniqueId の代わりに userId を渡しています	IG エンドポイントでは、ハンドルを uniqueId として指定します。古いスキーマが残っているクライアントで特によく発生します
npx のインストールで EACCES: permission denied が発生する	npx キャッシュの権限に問題があります	rm -rf ~/.npm/_npx を実行してから、再度インストールします
Error: ENOENT または cannot find dist/index.js が発生する	方法 B で npm run build を実行していません	リポジトリに cd して、npm install && npm run build を実行します
ツールの説明がこの README と異なり、古いように見える	古いバージョンのスキーマがキャッシュされています	claude mcp remove creatordb && claude mcp add … を実行して、スキーマを再取得します

再起動が重要な理由 — MCP クライアントはセッション開始時にツール一覧を一度だけ取得します。サーバーの更新（新しいツール、パラメーター名の変更、コストの修正）は、クライアントの再接続後にのみ反映されます。これは最もよくある混乱の原因です。

公開済みの新しいバージョンにアップグレードする場合 npx は正確なバージョンごとにパッケージをキャッシュするため、設定済みのクライアントは最初にダウンロードしたバージョンを使い続けます。最新バージョンを強制的に取得するには、設定で @latest を指定する（npx -y @creatordbai/mcp-server@latest は起動のたびに再解決します）か、npx キャッシュを一度削除します（rm -rf ~/.npm/_npx）。その後、MCP クライアントを再起動します。

リリース（メンテナー向け）

.github/workflows/release.yml ワークフローは、v*.*.* タグがプッシュされるたびに npm に公開します。

# bump version, commit, tag, push
npm version patch              # or minor / major
git push && git push --tags

このワークフローでは、タグが package.json の version と一致することを検証し、npm ci を実行してビルドした後、npm Trusted Publishing を使って sigstore の来歴証明を付与して公開します。長期間有効な NPM_TOKEN は保存されません。ワークフローの実行時に、GitHub OIDC トークンを有効期限の短い npm 公開トークンと交換します。

ロードマップ

• 目標：MCP レジストリと Claude の MCP マーケットプレイスに掲載し、ユーザーがクライアント内から MCP サーバーを閲覧したときに、このサーバーが表示されるようにします。
• 貢献、課題の報告、フィードバックを歓迎します。下記のヘルプの利用をご覧ください。

ツール

6 つのカテゴリーにわたる 43 個のツールがあります。各ツールは、構造化された JSON ペイロードと Credits used: N | Remaining: M のフッター行を返します。

アカウント（1）

ツール	コスト	備考
get_api_usage	0	エンドポイントごとの日次リクエスト数とクレジット消費量です。デフォルトでは直近 7 日間が対象です。省略可能な start／end Unix ミリ秒タイムスタンプを指定できます。

検索（4）

ツール	コスト	備考
search_creators_nls	動的（トークンベース）	3つのプラットフォームすべてを対象に、自然言語で検索します。AI がプラットフォームを選び、クエリをフィルターに変換します。
search_youtube	フィルター10件ごとに1	構造化フィルター検索です。件数のしきい値には totalSubscribers を使用します。
search_instagram	フィルター10件ごとに1	構造化フィルター検索です。件数のしきい値には totalFollowers を使用します。
search_tiktok	フィルター10件ごとに1	構造化フィルター検索です。件数のしきい値には totalFollowers を使用します。

フィルター型に関する注意点： 数値演算子（登録者数／フォロワー数／率のフィールドに対する >、<、=）には、数値文字列ではなく数値を指定する必要があります。"1000000" → VALIDATION_ERROR；1000000 → OK。

フィルター値に関する注意点： ハッシュタグの値は、先頭に # が付いていても付いていなくても一致し、大文字と小文字は区別されません。比率とパーセンタイルのフィールド（audienceMaleRatio、audienceFemaleRatio、および YouTube の *Percentile フィールド）には、0～100 ではなく 0～1 の小数を指定します。0.6 = 60%、0.9 = 上位10%。

スポンサー／ブランドデータ（8）

ブランド側のインテリジェンス：クリエイターをスポンサーしているブランド、支出額、提携しているクリエイターを確認できます。スポンサーのデータはYouTube と Instagram のみを対象としています。TikTok はブランドデータのインデックスに含まれていません。

ブランドキー：brandId。通常、ブランドのプライマリドメインです（例："acer.com"、"nike.com"）。

ツール	コスト	返される内容
search_sponsors	ページごとに2	構造化フィルターによるブランド検索です。簡易レコード（brandId、name、logo、industries、country）を返します。
list_sponsors	ページごとに1	インデックス登録済みの10,000以上のブランドをすべて掲載する、ページ分割されたディレクトリです。
get_sponsor_information	2	ブランドの完全なプロフィール：aliases、keyPeople、industries、location、website、socialMedia、competitors。
get_sponsor_creators	ページごとに25	get_*_sponsorship の逆方向の検索です。このブランドがスポンサーしたクリエイターを確認できます。クリエイターごとに followers、lastSponsoredDate、sponsoredCount、topics、niches を返します。
get_sponsor_performance	ページごとに25	コンテンツごとのスポンサーシップ実績です。クリエイターごとに3つの統計スコープ（creatorTotal、allSponsored lifetime、this-brand-only）があります。YT のみ：estimatedCost、CPM。
get_sponsor_audience	25	ブランドがスポンサーするクリエイター群全体のオーディエンス属性を集計して返します。IG ブロックは予約されていますが、現在は null です（バックエンドは YT のみ）。
get_sponsor_summary	25	クロスプラットフォームの集計：totalSponsoredCreators／Content、プラットフォームごとのクリエイター数＋実績＋growth30d。
submit_sponsor	1（重複の場合は0）	インデックス登録用にブランドを送信します。キーごとに1日100件までに制限されています。submissionId と status を返します。

コストに関する警告 — get_sponsor_creators、get_sponsor_performance、get_sponsor_audience、get_sponsor_summary は、呼び出しごとにそれぞれ25クレジットかかります。まずは低コストの search_sponsors／list_sponsors／get_sponsor_information を使って調べてください。

YouTube クリエイターデータ（7 + プラットフォーム固有の4）

クリエイターキー：channelId（UC…形式。@handle／/c/／/user/ の URL は受け付けられません。先に解決してください）。

ツール	コスト	返されるデータ
get_youtube_profile	2	本人情報、登録者数、国、言語、連携済みソーシャルアカウント、チャンネルカテゴリ、クリエイターの topics と niches。
get_youtube_contact	15	メールアドレス。
get_youtube_performance	3	R20（直近20本の動画）および全期間（最大800本）のエンゲージメント指標、一貫性スコア、30日／90日の視聴回数。
get_youtube_performance_history	3	過去N日間の日次スナップショット。pastDayRange（整数を文字列で指定、1～365）を受け取ります。
get_youtube_audience	10	年齢層、性別の割合、上位の国。
get_youtube_content_detail	3	直近の動画とショート動画、および各コンテンツのエンゲージメント。
get_youtube_sponsorship	5	インデックス済みブランドごとにまとめたスポンサー付きコンテンツ（直近の投稿のみ。リストが空でも「スポンサーなし」とは限りません）。
list_youtube_topics	1	YT TOPIC タクソノミー（channelCount を含む約470件）のページネーション。YouTube 専用です。IG と TT にはトピックタクソノミーがありません。 search、category、minChannelCount、pageSize、offset。
list_youtube_niches	1	YT NICHE タクソノミー（channelCount を含む約16K件）のページネーション。search、category、minChannelCount、pageSize、offset。
get_youtube_subtitles_meta	1	動画ごとの字幕トラック一覧。channelId ではなく videoId を受け取ります。
get_youtube_subtitles_download	3	1本の動画の字幕テキスト。videoId と、任意で language（ISO 639-3）を受け取ります。

Instagram クリエイターデータ（7 + 1）

クリエイターキー：uniqueId（ハンドル。@ は付けません）。

ツール	コスト	返されるデータ
get_instagram_profile	2	本人情報、フォロワー数、国、言語、isBusinessAccount、連携済みソーシャルアカウント、ハッシュタグ、アカウントカテゴリ、クリエイターの niches。
get_instagram_contact	15	メールアドレス。
get_instagram_performance	2	1ページ目の画像とリールのエンゲージメント、一貫性スコア。
get_instagram_performance_history	3	過去N日間の日次スナップショット。pastDayRange を受け取ります。
get_instagram_audience	10	年齢層、性別の割合、上位の国。
get_instagram_content_detail	2	直近の画像とリール、および各コンテンツのエンゲージメント。
get_instagram_sponsorship	5	インデックス済みブランドごとにまとめたスポンサー付きコンテンツ（直近の投稿のみ）。
list_instagram_niches	1	IG NICHE タクソノミー（約40K件）のページネーション。Instagram には「topics」タクソノミーがありません。 search、minChannelCount、pageSize、offset。

TikTok クリエイターデータ（7 + 1）

クリエイターキー：uniqueId（ハンドル。@ は付けません）。

ツール	コスト	返されるデータ
get_tiktok_profile	2	本人情報、フォロワー数、国、言語、ハッシュタグ、クリエイターの niches。
get_tiktok_contact	15	メールアドレス。
get_tiktok_performance	2	直近の動画のエンゲージメント（視聴回数、いいね、コメント、シェア）、一貫性スコア。
get_tiktok_performance_history	3	過去N日間の日次スナップショット。pastDayRange を受け取ります。
get_tiktok_audience	10	年齢層、性別の割合、上位の国。
get_tiktok_content_detail	2	音声メタデータ、デュエット／スティッチ／コマースのフラグ、各コンテンツのエンゲージメントを含む直近の動画。
search_tiktok_content	1ページあたり2	コンテンツレベルのフィルターを使って個別の動画を検索します。クリエイターを検索する search_tiktok とは異なります。isSponsored／partneredBrands はありません（TT のブランド帰属機能は未実装です）。フィルターの用語には diggs を使いますが、応答では likes に正規化されます。
list_tiktok_niches	1	TT NICHE タクソノミー（約40K件）のページネーション。TikTok には topics タクソノミーがなく、ブランドごとのスポンサーシップ用エンドポイントもありません。 search、minChannelCount、pageSize、offset。

クロスプラットフォームの違い早見表

項目	YouTube	Instagram	TikTok
クリエイターのパラメーター	channelId (UC…)	uniqueId (ハンドル)	uniqueId (ハンドル)
フォロワー数のフィールド	totalSubscribers	totalFollowers	totalFollowers
トピック分類体系の有無	✅ list_youtube_topics	❌	❌
ニッチ分類体系の有無	✅ list_youtube_niches	✅ list_instagram_niches	✅ list_tiktok_niches
/profile 内のクリエイターごとのニッチ	✅	✅	✅
/profile 内のクリエイターごとのトピック	✅	❌	❌
ブランドごとのスポンサーシップ用エンドポイント	✅	✅	❌
/content-detail のコンテンツタイプ	動画 + ショート動画	画像 + リール	動画
/content-detail のコスト	3	2	2
パフォーマンスの期間	R20 + 全期間（最大800件）	最初のページ	最新
エンゲージメントの計算式	(L+C+V) / 登録者数	(L+C) / フォロワー数	(L+C+Shares) / フォロワー数
字幕エンドポイント	✅	❌	❌
コンテンツ検索エンドポイント	✅	✅	✅
ブランド側のスポンサー情報	✅	✅	❌

ニッチ ID はプラットフォーム間で互換性がありません。id_vlog_PeopleBlogs (YT) と id_love_All (IG) は異なる名前空間に属します。ニッチ ID／トピック ID は id_{slug}_{Category} のパターンに従うため、最後の _ で分割すればカテゴリごとにグループ化できます。

レスポンス形式の注目点

以下は、エンドポイント名からは分かりにくいものの、頻繁に利用するフィールドです。すべてライブレスポンスで確認済みです。

/profile

YT／IG／TT 共通：

• subscriberGrowth: { g7, g30, g90 } — 過去7／30／90日間の登録者数／フォロワー数の変化率（%）です。無料で利用できるトレンド指標です。概要の数値だけが必要なら、performance-history を呼び出す必要はありません。
• hashtags: [{ name, contentCount }] — クリエイターが使用するハッシュタグです（注：IG／TT では name に # が含まれます）。
• niches: ["id_vlog_PeopleBlogs", …] — クリエイターごとのニッチ ID です。人が読める名前、カテゴリ、チャンネル数を取得するには、list_{platform}_niches を参照してください。
• relatedCreators — プラットフォーム自体がクリエイターの関連アカウントとして推奨または掲載するアカウントです。YT：YouTube がこのチャンネルの動画とともに推奨するチャンネルの UC channelId（頻度順）。IG／TT：プラットフォームから渡されたハンドルです。TikTok では、リストにクリエイター自身のハンドルが含まれることがよくあります。シードリストを拡張する手軽な方法です。
• hasEmail — get_{platform}_contact がメールアドレスを返すかどうかを示します。連絡先情報に15クレジットを支払う前に、fields で取得してください（0.1クレジット）。
• isAgencyRepresented — CreatorDB に代理店による所属の記録がある場合は true です。false には記録のないクリエイターも含まれます。
• lastPublishTime / lastDbUpdateTime — Unix ミリ秒です。組み合わせることで、スナップショットの古さと、クリエイターの直近の投稿時期を把握できます。
• country — ISO 3166-1 alpha-3（例："USA"、"JPN"）です。IG では自己申告フィールドではなく、コンテンツ分類器から導出された値です。複数の国で活動するクリエイターでは誤っている場合があるため、正確さが重要な場合は audienceLocations とクリエイターのプロフィール文を照合してください。

YT のみ：

• topics: ["id_challenges_Comedy", …] — 大まかなトピック ID（約470種類）です。list_youtube_topics で確認できます。
• totalViews — チャンネルの累計視聴回数です。チャンネルの「概要」パネルに表示される数値と同じです。
• スポンサー付き動画／ショート動画の CPM と料金帯（videoPrice、shortsPrice）は、現在プロフィールには含まれません。get_youtube_performance にあります。
• categoryBreakdown: [{ category, share }] — YouTube ネイティブカテゴリ別の最近のコンテンツの割合です。
• hasMemberOnlyContents — ブール値です。

IG のみ：

• isBusinessAccount、isPrivateAccount — オーディエンスデータを提示する前に確認する価値のあるフラグです。非公開アカウントはスクレイピングできません。
• otherLinks — プロフィール文にあるリンクの配列です。
• imageLastPublishTime / reelsLastPublishTime — 直近の画像投稿とリールの投稿時刻（Unix ミリ秒）です。lastPublishTime は2つのうち新しい方です。

TT のみ：

• otherLinks — プロフィール文にあるリンクです（TikTok では1つ設定できます）。
• joinedDate — アカウント作成時刻（Unix ミリ秒）です。

/audience

プラットフォーム間で構造は同一です。

• audienceLocations: [{ country, share }] — 上位6か国とそのシェア。合計はおよそ1.0です。
• audienceGender: { maleRatio, femaleRatio } — 合計は約1.0です。男女の2区分のみです。
• audienceAvgAge — 整数です。
• audienceAgeBreakdown: [{ ageRange, share }] — 固定の年齢区分は 13-17 | 18-24 | 25-34 | 35-44 | 45-54 | 55-64 | 65+ です。常に7件あり、プレースホルダーの行はすべてゼロです（下記の注意点一覧を参照）。

/performance

R20と全期間の区別があるのはYTのみです。

• YTは、兄弟オブジェクトとして videosPerformanceRecent、videosPerformanceAll、shortsPerformanceRecent、shortsPerformanceAll の4つを返します。「Recent」はR20（直近20件）です。「All」は最大800件です。それぞれに likes/comments/views（avg/median/min/max/percentile25/percentile75/iqr を含む）と engagement ブロックがあります。
• IGは imagesPerformanceRecent と reelsPerformanceRecent を返します。全期間のデータはありません。
• TTは videosPerformanceRecent を返します。全期間のデータはありません。
• すべての engagement ブロックの末尾には、engagementConsistency: { cv, medianVsMean, topBottomRatio, consistencyScore, consistencyLevel } があります。consistencyScore は0～100です。consistencyLevel は "high"（81～100）、"moderate"（51～80）、または "low"（0～50）です。コンテンツが6件以上必要です。それ未満の場合、整合性ブロックは含まれません。
• ranking ブロックには、totalSubscribers／totalFollowers と avgEngagementRate の、グローバル、国別、言語別のパーセンタイル順位が含まれます。別途ベンチマークを行わずに「このクリエイターは自国の平均を上回っているか」を判断する際に役立ちます。
• recentVideosGrowth.g7/g30/g90 — 7日／30日／90日間のエンゲージメント率の変化です。負の値はエンゲージメントが低下していることを示します。
• contentCountByDays: { 7d, 30d, 90d } — 各期間内の投稿数です（活動休止中のクリエイターの判別に使用します）。

/content-detail

プラットフォーム共通の各アイテムのオブジェクトです。

• publishTime（Unixミリ秒）、contentId、likes、comments、views（YT／TTのみ。IGの画像には再生回数がありません）、engagementRate（小数点以下4桁に丸められています）。
• hashtags: ["#example", …] — # のプレフィックスはすでに含まれています。

プラットフォーム固有の追加項目：

• YT：length（秒）、isMemberOnly。コンテンツの種類には動画とショートの両方が含まれます。
• IG：mentionedCreators — キャプション内の @ メンションです。
• TT：audioId、audioTitle、audioAuthor、audioAlbum、isDuetEnabled、isAd、length（秒）、shares。トレンドの音源を見つけるには、音源ブロックを使うのが最も手軽です。

鮮度ルール — 直近4日以内に公開されたコンテンツは、すべての指標の計算から除外されます（全プラットフォーム共通）。ピン留め投稿のルール — IG／TTでは、90日より前のピン留め投稿がサンプル内で最も古いアイテムになる場合、その投稿は除外されます。

/sponsorship

YTとIGのみです。TikTokにはブランドごとのスポンサーシップエンドポイントがありません。

• sponsorList: [{ brandName, brandId, brandIgIds, sponsoredVideos, sponsoredVideosPerformance }]。
• brandIgIds — ブランドのIGハンドルです。スポンサー付きクリエイターから、そのブランド自身のプロフィールをたどる際に使用します。
• sponsoredVideos には、スポンサー付きコンテンツごとの完全なアイテム単位のエンゲージメントデータが含まれます（/content-detail と同じ構造です）。
• 重要な注意点 — 直近のおよそ20～30件の投稿のみをスキャンし、CreatorDBにすでにインデックス登録されているブランドのみを検出します。sponsorList が空でも、クリエイターにスポンサーがいない証拠にはなりません。「直近の投稿から、インデックス登録済みのスポンサーを見つけられなかった」という意味です。

検索（search_{platform} および search_creators_nls）

構造化検索レスポンス：

• creatorList: [{ displayName, uniqueId, channelId (YT only), avatarUrl, totalSubscribers | totalFollowers }] — 最小限のフィールドのみを返します。全データを取得するには、get_*_profile で補完してください。
• totalResults — ページ内の件数ではなく、フィルター条件に一致する総件数です。
• hasNextPage + nextOffset — ページネーションの形式です。次のリクエストの offset に nextOffset を渡すと、次のページに進みます。

NLS レスポンス：

• 構造化検索と同じ形式の creatorList に、AI がルーティングしたプラットフォームを示す platform: "youtube" | "instagram" | "tiktok" フィールドが加わります。
• 内部では SSE 経由でストリーミングされます。MCP レイヤーが最後の data: イベントを収集し、1 つのペイロードとして返します。
• 料金は動的に変動し、通常は入力と出力のトークン数に応じて 1～10 クレジットです。

/usage

• records: [{ date (YYYYMMDD), requestCount, totalQuotaUsed, endpoints: { …per-endpoint counts }, platforms: { …per-platform counts }, quotaByPlatform }]。
• totalQuotaUsed は小数になる場合があります（例：NLS 呼び出しで 4.49）。
• endpoints のキーはキャメルケースです（getYoutubeProfile、getInstagramAudience、searchYoutube、getNLS など）。利用額ダッシュボードの作成に役立ちます。

よくある落とし穴

• プレースホルダーのオーディエンス属性：CreatorDB に実際のオーディエンスデータがない場合、/audience はすべてゼロの形式（audienceGender: { maleRatio: 0, femaleRatio: 0 }、年齢層の値もすべて 0.0）を返します。男性比率と女性比率の合計が 0 の行は、「性別データなし」ではなく、データ欠損として扱ってください。
• sponsorList が空でもスポンサーがいないとは限りません（上記を参照）。
• relatedCreators は順位付けされていません。並び順に意味はありません。先頭から N 件を切り出して「関連度上位」と呼ぶのではなく、サンプリングするか、独自の指標で順位を付け直してください。
• データの鮮度に遅れがあります。lastDbUpdateTime は CreatorDB が最後にデータを更新した日時です。約 14 日より古い場合、プロフィールに最近急伸したコンテンツが反映されていない可能性があります。
• ニッチの channelCount は変動します。list_*_niches は毎日更新されます。キャッシュはそれより長く保持しないでください。そうしないと、「X のニッチに属するクリエイター数」が実状とずれていきます。
• 分類体系はページングせず、検索してください。list_*_niches は一度に 1 ページ（デフォルトは 100 件、件数の多い順）を返します。Instagram と TikTok の分類体系は約 40,000 件に及ぶためです。どちらも閲覧できる階層のない単一のフラットな「All」カテゴリーで、上位 100 件に該当するクリエイターは全体の割り当ての約 18％にすぎないため、ページを進めてもあまり意味がありません。代わりに search を渡して、フレーズに対応するニッチ名を検索してください。検索は単語全体に一致するため、skin では Skincare は見つかりません。キャメルケースの名前は分割され（StreetFood は street food に一致）、一般的な表記の違いは吸収されます（vloggers→vlog、japanese→japan）。TikTok では約 44％のニッチがクリエイター数 100 未満です。minChannelCount でこの少数グループを除外できます。
• Instagram の country はモデルによる推定で、本人の申告ではありません。YouTube と TikTok では、クリエイターが自身のプロフィールに設定した国が返されます。Instagram では CreatorDB の位置情報モデルが国を割り当てるため、プロフィールに何も記載されていない場合でも国のデータが得られます。

フィルターリファレンス（検索ツール）

3 つのプラットフォームに共通するフィールド：

• displayName — 文字列。あいまい検索に対応
• uniqueId — 文字列。完全一致
• country — 文字列。ISO 3166-1 alpha-3（例："USA"、"JPN"、"GBR"）
• mainLanguage — 文字列。ISO 639-3（例："eng"、"jpn"、"zhs"）
• hashtags — 文字列（IG／TT では # を付けます）
• niches — 文字列（各プラットフォームの list_*_niches の ID を使用）
• mainAudienceLocation / mainAudienceAge / mainAudienceGender — 文字列
• hasSponsors — ブール値

プラットフォーム固有：

• YouTube：totalSubscribers（数値）、topics（list_youtube_topics の文字列）
• Instagram／TikTok：totalFollowers（数値）

演算子：数値には >、<、=、文字列には =、in、ブール値には = を使用します。in には最大 100 個の値を配列で指定できます。pageSize の最大値は 100、1 リクエストあたりの filters の最大数は 10 です。

レスポンスエンベロープ

すべてのツールは、CreatorDB V3 の基盤となるエンベロープを返します。

{
  "data": { },
  "creditsUsed": 2,
  "creditsAvailable": 953270.5,
  "traceId": "abc-123",
  "timestamp": 1779722787120,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}

エラーが発生した場合、エンベロープには errorCode、error、message、details が含まれます。MCP レイヤーはこれを、サポート用の TraceId: 行を含む簡潔なエラーメッセージに変換します。

開発

npm run dev   # tsc --watch
npm run build # tsc once
npm start     # node dist/index.js

ソースの構成：

src/
  index.ts                 # registers all tools, stdio transport
  tools/
    account.ts             # 1 tool
    search.ts              # 4 tools (NLS + 3 platform creator searches)
    youtube.ts             # 12 tools
    instagram.ts           # 9 tools
    tiktok.ts              # 9 tools (incl. search_tiktok_content)
    sponsors.ts            # 8 tools (brand-side sponsor intelligence)
  util/
    api-client.ts          # fetch wrapper for REST + SSE
    response.ts            # MCP result formatter (credits, errors)

サポートを受ける

• バグ／機能リクエスト／新しいエンドポイントへの対応：https://github.com/CreatorDB/creatordb-mcp-server/issues でイシューを作成してください
• API キー／データに関するお問い合わせ：[email protected]
• マシンへのインストールを試しているだけですか？ SETUP.md をご覧ください。コントリビューターではなく、エンドユーザー向けの 5 分間ガイドです。

ライセンス

MIT