CreatorDB

creatordb-mcp-server

一个 模型上下文协议 服务，可将 CreatorDB V3 API 提供给任何兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）。

六大类别，共 43 个工具：

• 创作者数据 — YouTube、Instagram 和 TikTok 上创作者的个人资料、表现、受众人口统计数据、联系方式、内容详情和历史表现
• 创作者搜索 — 跨三个平台进行自然语言搜索，以及按平台进行结构化筛选搜索（国家/地区、语言、粉丝数阈值、细分领域、话题标签、受众人口统计数据等）
• 品牌端 / 赞助方情报 （仅限 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 搜索仍可用。）
• 主题 + 细分领域分类体系 — 可分页、可搜索的目录（约 470 个 YT 主题、约 16K 个 YT 细分领域，以及 IG/TT 各约 40K 个），用于解析个人资料响应中返回的创作者主题 / 细分领域 ID。传入 search 可将短语解析为条目名称，无需分页。
• 账户 — 按端点和平台细分的积分使用情况。

每个工具都会返回底层 V3 JSON，并附带 Credits used: N | Remaining: M 页脚，让 AI 准确了解积分消耗情况。

正在使用 Claude Code？ 在 Claude Code 中打开此 README（或将 URL 粘贴到 Claude 会话中），然后说 “帮我设置此 MCP。” 以下步骤按顺序编写，方便 AI 助手逐步执行。

快速开始

根据客户端不同，有两种连接方式：

• 本地客户端（Claude Code、Claude Desktop、Cursor）通过 npx 将服务作为子进程运行 — 请参阅 安装（本地 / stdio）。
• Web / 桌面 / 移动客户端连接到托管端点，或直接从 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。服务读取一个环境变量：CREATORDB_API_KEY（你的 V3 密钥）。

方法 A — 从 npm 使用 npx（推荐）

该软件包已作为 @creatordbai/mcp-server 发布到 npm。无需本地克隆、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 组织访问权限，并希望跟踪 main 而不是 npm 发行版，可将 npm 包名替换为 git+ssh://[email protected]/CreatorDB/creatordb-mcp-server.git — 仓库的 prepare 脚本会在安装时构建。

方法 B — 克隆并在本地构建

适用于想要阅读／修改源代码，或在你的环境中 npx 无法从 git 运行的情况。

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} 会从用户的 shell 环境中读取，因此密钥不会进入 git。每位队友只需在自己的 .zshrc／.bash_profile 中设置一次：

export CREATORDB_API_KEY=YOUR_CREATORDB_API_KEY

远程连接器（Claude 网页版、桌面版、移动版）

无法启动本地子进程的 Claude 客户端会连接托管端点，而不是运行 npx。有两种接入方式。

通过连接器目录（最简单）。 CreatorDB 已列入 Claude 的连接器目录。在 Claude 中：Settings → Connectors → Add → Browse connectors，搜索 CreatorDB，打开 CreatorDB MCP，然后点击 Connect to Claude。

手动添加。 你也可以直接添加：Settings → Connectors → Add → Add custom connector，然后输入 URL：

https://mcp.creatordb.app/mcp

高级 OAuth Client ID／Secret 字段留空即可，服务器会自动注册客户端。

无论使用哪种方式，连接时系统都会提示你输入 CreatorDB API 密钥，之后会显示相同的 43 个工具。

说明：

• 连接时系统会提示你输入密钥；连接器会将其封装到加密的会话令牌中，不会保留单独副本。CreatorDB 仅将该密钥作为其签发给你的凭据存储。
• 直接调用该端点的程序化客户端也可以改为发送 Authorization: Bearer <your CreatorDB V3 API key>。
• 健康检查：https://mcp.creatordb.app/health（无需身份验证，不消耗积分）——服务正常运行时返回 {"status":"ok",...}。
• 作为 Firebase Cloud Function（gen 2）托管在 asia-northeast1；源代码位于 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 设置界面）
• Claude Code： ~/.mcp.json 或项目的 .mcp.json

更改 CREATORDB_API_KEY 的值，然后完全重启客户端（Claude Desktop 按 ⌘Q 后重新打开，重启 Cursor 应用等）。MCP 客户端仅在进程启动时读取密钥。

如果你通过 shell 环境设置了密钥（上面方法 C 中使用 ${CREATORDB_API_KEY} 语法），请更新 ~/.zshrc / ~/.bash_profile，并在重启客户端前重启终端。

远程连接器（Claude 网页版、桌面版、移动版）

在 Settings → Connectors → CreatorDB 中断开连接并重新连接，然后在提示时输入新密钥。（使用 Bearer 令牌的程序化客户端只需开始发送新密钥即可。）

更换已泄露密钥时需要了解的一点

在客户端更换密钥，只会切换工具用于身份验证的密钥。这不会使之前的密钥失效。 如果你是因为旧密钥已泄露而更换：

1. 前往你的 CreatorDB 账户并在那里撤销旧密钥——这才会让它在 V3 API 层真正失效。
2. 然后按照上述说明更新 MCP 客户端，使其使用新密钥。

MCP 服务不会在单次请求之后保留你的密钥，因此无需清除服务端的“已存储密钥”。

验证是否正常工作

安装后，重启 Claude Code（或你的 MCP 客户端），然后：

1. 运行 /mcp — 你应该会看到 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	传入了 userId 而非 uniqueId	IG 端点使用 uniqueId 接收用户名。使用过期架构的旧客户端最容易遇到此问题
npx 安装失败，报错 EACCES: permission denied	npx 缓存权限问题	运行 rm -rf ~/.npm/_npx，然后重试
出现 Error: ENOENT 或 cannot find dist/index.js	方法 B 未运行 npm run build	进入仓库目录并运行 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 客户端。

发布（维护者）

每当推送 v*.*.* 标签时，.github/workflows/release.yml 工作流都会发布到 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 服务时能找到此服务。
• 欢迎贡献、提交问题和反馈 — 请参阅下方的获取帮助。

工具

六个类别共包含 43 个工具。每个工具都会返回结构化 JSON 数据，以及一行 Credits used: N | Remaining: M 页脚。

账户（1）

工具	成本	说明
get_api_usage	0	按端点统计每日请求次数和额度消耗。默认查询最近 7 天；可选传入 start/end Unix 毫秒时间戳。

搜索（4）

工具	费用	说明
search_creators_nls	动态（基于 token）	使用自然语言搜索三个平台。AI 会选择平台，并将查询转换为筛选条件。
search_youtube	每 10 个筛选条件 1 点	结构化筛选搜索。计数阈值使用 totalSubscribers。
search_instagram	每 10 个筛选条件 1 点	结构化筛选搜索。计数阈值使用 totalFollowers。
search_tiktok	每 10 个筛选条件 1 点	结构化筛选搜索。计数阈值使用 totalFollowers。

筛选类型注意事项： 数值运算符（订阅者 / 粉丝 / 费率字段上的 >、<、=）要求值为数字，而不是数字字符串。"1000000" → VALIDATION_ERROR；1000000 → 正常。

筛选值说明： 标签值无论带不带前导 # 都能匹配，且不区分大小写。比率和百分位字段（audienceMaleRatio、audienceFemaleRatio 和 YouTube 的 *Percentile 字段）接受 0 到 1 之间的小数，而不是 0 到 100：0.6 = 60%，0.9 = 前 10%。

赞助商 / 品牌数据（8）

品牌侧情报：哪些品牌赞助了哪些创作者、投入了多少、与哪些创作者合作。赞助数据仅涵盖 YouTube 和 Instagram——品牌索引中不包含 TikTok。

品牌键：brandId，通常为品牌的主域名（例如 "acer.com"、"nike.com"）。

工具	费用	返回内容
search_sponsors	每页 2 点	按结构化筛选条件搜索品牌。精简记录（brandId、名称、徽标、行业、国家 / 地区）。
list_sponsors	每页 1 点	所有 10K+ 已索引品牌的分页目录。
get_sponsor_information	2 点	完整品牌档案：别名、关键人物、行业、位置、网站、社交媒体、竞争对手。
get_sponsor_creators	每页 25 点	与 get_*_sponsorship 相反——查询该品牌赞助过哪些创作者。返回每位创作者的粉丝数、lastSponsoredDate、sponsoredCount、主题和细分领域。
get_sponsor_performance	每页 25 点	按内容统计赞助表现。每位创作者有三个统计范围（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 点）	提交品牌以供编入索引。每个 key 每天限 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 个）的互动指标；稳定性评分；30d/90d 观看量时间窗口。
get_youtube_performance_history	3	过去 N 天的每日快照。接受 pastDayRange（字符串整数，1–365）。
get_youtube_audience	10	年龄区间、性别比例、主要国家/地区。
get_youtube_content_detail	3	近期视频 + Shorts，以及各条内容的互动数据。
get_youtube_sponsorship	5	按索引品牌归类的赞助内容（仅限近期帖子——列表为空 ≠“没有赞助商”）。
list_youtube_topics	1	YT TOPIC 分类体系（约 470 个条目，含 channelCount），支持分页。仅限 YouTube——IG 和 TT 没有 topic 分类体系。 search、category、minChannelCount、pageSize、offset。
list_youtube_niches	1	YT NICHE 分类体系（约 16K 个条目，含 channelCount），支持分页。search、category、minChannelCount、pageSize、offset。
get_youtube_subtitles_meta	1	每个视频的字幕轨道列表。接受 videoId（而非 channelId）。
get_youtube_subtitles_download	3	单个视频的字幕文本。接受 videoId，以及可选的 language（ISO 639-3）。

Instagram 创作者数据（7 + 1 个）

创作者标识：uniqueId（不含 @ 的用户名）。

工具	费用	返回内容
get_instagram_profile	2	身份信息、关注者数量、国家/地区、语言、是否为企业账号、关联社交账号、话题标签、账号类别，以及创作者的 niches。
get_instagram_contact	15	电子邮件地址。
get_instagram_performance	2	首页图片 + Reels 互动数据；稳定性评分。
get_instagram_performance_history	3	过去 N 天的每日快照。接受 pastDayRange。
get_instagram_audience	10	年龄区间、性别比例、主要国家/地区。
get_instagram_content_detail	2	近期图片 + Reels，以及各条内容的互动数据。
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	每页 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 (handle)	uniqueId (handle)
粉丝数字段	totalSubscribers	totalFollowers	totalFollowers
是否有主题分类体系	✅ list_youtube_topics	❌	❌
是否有细分领域分类体系	✅ list_youtube_niches	✅ list_instagram_niches	✅ list_tiktok_niches
/profile 中的创作者细分领域	✅	✅	✅
/profile 中的创作者主题	✅	❌	❌
按品牌查询赞助的接口	✅	✅	❌
/content-detail 中的内容类型	视频 + Shorts	图片 + Reels	视频
/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_{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 交叉查询，获取易读名称、类别和 channelCount。
• relatedCreators — 平台自身推荐或列为与该创作者相关的账号。YT：YouTube 在该频道视频旁推荐的频道 UC channelId，按出现频率从高到低排列。IG/TT：handle，按平台提供的内容传递。在 TikTok 上，列表通常包含创作者自己的 handle。这是扩展种子列表的低成本方式。
• hasEmail — get_{platform}_contact 是否会返回邮箱。可先通过 fields 请求此字段（0.1 点），再决定是否支付 15 点获取联系方式。
• 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 — 频道的累计观看次数，与频道“简介”面板中显示的相同。
• joinedDate — 频道创建时间（Unix 毫秒，精确到天）。
• 赞助视频 / Shorts 的 CPM 和报价区间（videoPrice、shortsPrice）已不再位于 profile 中；它们位于 get_youtube_performance。
• categoryBreakdown: [{ category, share }] — YouTube 原生类别中近期内容所占的比例。
• hasMemberOnlyContents — 布尔值。

仅限 IG：

• isBusinessAccount、isPrivateAccount — 在承诺提供受众数据前值得检查的标志；私密账号无法抓取。
• otherLinks — 简介中的链接数组。
• imageLastPublishTime / reelsLastPublishTime — 最新图片帖文和最新 Reels 的时间（Unix 毫秒）；lastPublishTime 为两者中较晚的时间。

仅限 TT：

• otherLinks — 简介中的链接（TikTok 仅允许一个）。
• joinedDate — 账号创建时间（Unix 毫秒）。

/audience

各平台的结构相同：

• audienceLocations: [{ country, share }] — 排名前 6 的国家，份额总和约为 1.0。
• audienceGender: { maleRatio, femaleRatio } — 总和约为 1.0；仅划分为两类。
• audienceAvgAge — 整数。
• audienceAgeBreakdown: [{ ageRange, share }] — 固定年龄段 13-17 | 18-24 | 25-34 | 35-44 | 45-54 | 55-64 | 65+。始终包含 7 条；占位行的值均为 0（参见下方注意事项列表）。

/performance

R20 与全部内容的区别仅适用于 YT：

• YT 返回 4 个同级对象：videosPerformanceRecent、videosPerformanceAll、shortsPerformanceRecent、shortsPerformanceAll。“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 的 global、country、language 百分位排名 — 无需单独进行基准比较，即可判断“这位创作者在其所在国家是否高于平均水平”。
• 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；内容组合包括视频和 Shorts。
• 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 — 分页惯用模式。将 nextOffset 作为下一次请求的 offset，即可继续获取结果。

NLS 响应：

• creatorList 的结构相同，另外还包含 platform: "youtube" | "instagram" | "tiktok" 字段，用于说明 AI 将请求路由到了哪个平台。
• 底层通过 SSE 流式传输；MCP 层会收集最终的 data: 事件，并将其作为一个负载返回。
• 动态定价 — 通常根据输入和输出 token 数量消耗 1–10 个额度。

/usage

• records: [{ date (YYYYMMDD), requestCount, totalQuotaUsed, endpoints: { …各端点的调用次数 }, platforms: { …各平台的调用次数 }, quotaByPlatform }]。
• totalQuotaUsed 可以是小数（例如，NLS 调用为 4.49）。
• endpoints 的键采用 camelCase 格式：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 每次只返回一页（默认 100 个，按数量从多到少排列），因为 Instagram 和 TikTok 的完整分类体系都接近 40,000 个条目。两者都只有一个扁平的“All”类别，没有可供浏览的层级结构；前 100 个条目只占创作者分类结果的约 18%，因此翻页通常收效甚微。请传入 search，将短语匹配到细分领域名称。匹配以完整单词为单位，因此 skin 不会匹配 Skincare；驼峰式名称会拆分（StreetFood 匹配 street food），常见变体也会归一化（vloggers→vlog，japanese→japan）。TikTok 上约 44% 的细分领域创作者不到 100 人；minChannelCount 可筛除这部分长尾结果。
• IG 的 country 是模型推断值，并非用户自行声明 — YouTube 和 TikTok 返回创作者在其个人资料中自行设置的国家/地区；对于 Instagram，该值由 CreatorDB 的位置模型提供，因此即使个人资料中未注明，IG 也可能有国家/地区信息。

筛选条件参考（搜索工具）

三个平台共有的字段：

• 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；每次请求的 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