creatordb-mcp-server

A Model Context Protocol server that exposes the CreatorDB V3 API to any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.).

42 tools across six surfaces:

• Creator-side data — profile, performance, audience demographics, contact, content-detail, performance history for YouTube, Instagram, and TikTok

• Creator search — natural-language search across all three platforms, plus structured filter search per platform (country, language, follower thresholds, niches, hashtags, audience demographics, etc.)

• Brand-side / sponsor intelligence (YouTube + Instagram only — TikTok brand data is not indexed) — search CreatorDB's 10K+ indexed brands, pull a brand's full profile, list every creator a brand has sponsored, get aggregated audience demographics across a brand's sponsored creator pool, and cross-platform spend / CPM / CPE rollups. Most sponsor read endpoints cost 25 credits each — use deliberately.

• Content search — find individual videos, reels, images, shorts, or TikToks by content-level filters (publish time window, view/like thresholds, hashtags, sponsored-vs-organic, language, niche, etc.). Different from creator search — this returns posts, not channels.

• Topic + niche taxonomies — full catalogs (~470 YT topics, ~14K YT niches, ~10K each on IG/TT) for resolving the per-creator topic/niche IDs returned in profile responses.

• Account — credit usage broken down by endpoint and platform.

Every tool returns the underlying V3 JSON plus a Credits used: N | Remaining: M footer line, so the AI knows exactly what it's spending.

Working with Claude Code? Open this README in Claude Code (or paste the URL into a Claude session) and say "set up this MCP for me." The steps below are written so an AI assistant can follow them top to bottom.

Quick start

1. Prerequisites

   • Node.js 22 or newer (node -v to check)

   • GitHub read access to CreatorDB/creatordb-mcp-server (this repo is private)

   • A CreatorDB V3 API key — get one from https://creatordb.app account settings, or ask your team admin

2. Pick an install method below (Method A is the fastest)

3. Restart your MCP client so it picks up the new tools

4. Verify by running /mcp in Claude Code — creatordb should appear with status connected

Install

The server reads one environment variable: CREATORDB_API_KEY (your V3 key).

Method A — npx from npm (recommended)

The package is published to npm as @creatordbai/mcp-server. No local clone, no SSH key, no GitHub access required:

Claude Code:

claude mcp add creatordb -s user \
  -e CREATORDB_API_KEY=sk-your-key-here \
  -- npx -y @creatordbai/mcp-server

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

If you have GitHub org access and want to track main instead of the npm release, swap the npm name for git+ssh://git@github.com/CreatorDB/creatordb-mcp-server.git — the repo's prepare script will build on install.

Method B — clone and build locally

Good if you want to read/modify the source, or if npx from git doesn't work in your environment.

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=sk-your-key-here \
  -- node "$(pwd)/dist/index.js"

For Claude Desktop, use the same JSON as Method A but swap command + args:

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

Method C — project-scoped via .mcp.json (best for teams)

Drop a .mcp.json into a CreatorDB project repo. Anyone who opens that repo in Claude Code gets prompted to enable the MCP — no per-person setup commands.

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

${CREATORDB_API_KEY} reads from the user's shell environment, so the key stays out of git. Each teammate sets it once in their .zshrc/.bash_profile:

export CREATORDB_API_KEY=sk-...

Verify it works

After install, restart Claude Code (or your MCP client) and:

1. Run /mcp — you should see creatordb listed with status connected

2. Ask Claude something that uses the tools, e.g. "use creatordb to look up the YouTube profile for MrBeast (channelId UCX6OQ3DkcsbYNE6H8uQQuVA)"

3. The response should include creator data and a Credits used: 2 | Remaining: … footer

Troubleshooting

Why restarts matter — MCP clients fetch the tool list once at session start. Server updates (new tools, renamed params, fixed costs) only show up after the client reconnects. This is the single most common confusion.

Upgrading to a newer published version? npx caches packages by exact version, so a configured client keeps running whatever version it first downloaded. To force-pull the latest, either pin to @latest in your config (npx -y @creatordbai/mcp-server@latest re-resolves each launch) or clear the npx cache once (rm -rf ~/.npm/_npx). Then restart the MCP client.

Releasing (maintainers)

The .github/workflows/release.yml workflow publishes to npm whenever a v*.*.* tag is pushed.

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

The workflow validates that the tag matches package.json version, runs npm ci, builds, and publishes via npm Trusted Publishing with sigstore provenance attestation. No long-lived NPM_TOKEN is stored — the workflow exchanges a GitHub OIDC token for a short-lived npm publish token at runtime.

Roadmap

• Goal: list in the MCP registry and Claude's MCP marketplace so the server shows up when users browse MCP servers from inside their client.

• Contributions, issues, and feedback welcome — see Getting help below.

Tools

42 tools across six categories. Every tool returns a structured JSON payload plus a Credits used: N | Remaining: M footer line.

Account (1)

Search (4)

Filter type gotcha: numeric ops (>, <, = on subscriber/follower/rate fields) require a number value, not a numeric string. "1000000" → VALIDATION_ERROR; 1000000 → ok.

Hashtag value gotcha: stored hashtags on IG/TT carry the leading #, so filter values usually want "#beauty", not "beauty".

Sponsors / brand data (8)

Brand-side intelligence: which brands sponsor creators, how much they spend, which creators they work with. Sponsor data covers YouTube and Instagram only — TikTok is not indexed for brands.

Brand-key: brandId, typically the brand's primary domain (e.g. "acer.com", "nike.com").

Cost warning — get_sponsor_creators, get_sponsor_performance, get_sponsor_audience, get_sponsor_summary each cost 25 credits per call. Use search_sponsors / list_sponsors / get_sponsor_information for cheap exploration first.

YouTube creator data (8 + 4 platform-specific)

Creator-key: channelId (the UC… form — @handle / /c/ / /user/ URLs are not accepted; resolve first).

Instagram creator data (8 + 1)

Creator-key: uniqueId (the handle, no @).

TikTok creator data (7 + 1)

Creator-key: uniqueId (the handle, no @).

Cross-platform differences cheat-sheet

Niche IDs are not interchangeable across platforms — id_vlog_PeopleBlogs (YT) and id_love_All (IG) live in different namespaces. Niche/topic IDs follow the pattern id_{slug}_{Category}, so you can group by category by splitting on the last _.

Response shape highlights

These are the fields that aren't obvious from the endpoint name but you'll reach for constantly. All confirmed against live responses.

/profile

Shared across YT/IG/TT:

• subscriberGrowth: { g7, g30, g90 } — % change in subscribers/followers over the last 7/30/90 days. Free trend signal — no need to call performance-history if you only want the headline number.

• hashtags: [{ name, contentCount }] — hashtags the creator uses (note: name carries the # on IG/TT).

• niches: ["id_vlog_PeopleBlogs", …] — per-creator niche IDs. To resolve the human-readable name + category + channelCount, cross-reference list_{platform}_niches.

• relatedCreators — discovery vector. YT gives ~50–250 UC channelIds; IG gives ~50 handles. Cheap way to expand a seed list.

• lastPublishTime / lastDbUpdateTime — Unix-ms; pair them to know how stale the snapshot is vs how recently the creator posted.

• country — ISO 3166-1 alpha-3 (e.g. "USA", "JPN"). On IG this value is derived from a content classifier rather than a self-declared field, and can occasionally be wrong for creators with multi-country presence — cross-check against audienceLocations and the creator's bio if accuracy matters.

YT-only:

• topics: ["id_challenges_Comedy", …] — coarse topic IDs (~470 universe). Resolve via list_youtube_topics.

• videoPrice + shortsPrice: { cpmLow, cpmRaw, cpmHigh, priceLow, priceRaw, priceHigh } — sponsored video / shorts CPM and dollar rate bands. YouTube-only; IG/TT do not return pricing in /profile.

• categoryBreakdown: [{ category, share }] — share of recent content by YouTube native category.

• hasMemberOnlyContents — boolean.

IG-only:

• isBusinessAccount, isPrivateAccount — flags worth checking before promising audience data; private accounts can't be scraped.

• otherLinks — bio links array.

TT-only:

• otherLinks — bio link (TikTok allows one).

/audience

Identical shape across platforms:

• audienceLocations: [{ country, share }] — top 6 countries with shares summing to roughly 1.0.

• audienceGender: { maleRatio, femaleRatio } — sums to ~1.0; binary split only.

• audienceAvgAge — integer.

• audienceAgeBreakdown: [{ ageRange, share }] — fixed buckets 13-17 | 18-24 | 25-34 | 35-44 | 45-54 | 55-64 | 65+. Always 7 entries; placeholder rows are all-zero (see footgun list below).

/performance

The R20-vs-all distinction is YT-only:

• YT returns four sibling objects: videosPerformanceRecent, videosPerformanceAll, shortsPerformanceRecent, shortsPerformanceAll. "Recent" = R20 (last 20). "All" = up to 800. Each has likes/comments/views (with avg/median/min/max/percentile25/percentile75/iqr) and an engagement block.

• IG returns imagesPerformanceRecent + reelsPerformanceRecent. No all-time window.

• TT returns videosPerformanceRecent. No all-time window.

• Every engagement block ends with engagementConsistency: { cv, medianVsMean, topBottomRatio, consistencyScore, consistencyLevel }. consistencyScore is 0–100; consistencyLevel is "high" (81–100), "moderate" (51–80), or "low" (0–50). Requires ≥6 content pieces, otherwise the consistency block is absent.

• ranking block carries global, country, language percentile ranks for totalSubscribers/totalFollowers and avgEngagementRate — useful for "is this creator above average for their country" without separate benchmarking.

• recentVideosGrowth.g7/g30/g90 — engagement-rate delta over 7/30/90 days. Negative numbers mean engagement is declining.

• contentCountByDays: { 7d, 30d, 90d } — how many posts in each window (use to detect dormant creators).

/content-detail

Per-item objects across platforms:

• publishTime (Unix-ms), contentId, likes, comments, views (YT/TT only — IG images have no view count), engagementRate (rounded to 4 decimals).

• hashtags: ["#example", …] — already includes # prefix.

Platform-specific extras:

• YT: length (seconds), isMemberOnly, content mix includes both videos and shorts.

• IG: mentionedCreators — @-mentions in caption.

• TT: audioId, audioTitle, audioAuthor, audioAlbum, isDuetEnabled, isAd, length (seconds), shares. The audio block is the cheapest way to find trending sounds.

Freshness rule — content published within the last 4 days is excluded from all metric calculations (all platforms). Pinned-post rule — on IG/TT, a pinned post older than 90 days is excluded if it would be the oldest item in the sample.

/sponsorship

YT and IG only — TikTok does not have a per-brand sponsorship endpoint.

• sponsorList: [{ brandName, brandId, brandIgIds, sponsoredVideos, sponsoredVideosPerformance }].

• brandIgIds — the brand's IG handles. Use this to follow a brand from a sponsored creator back to the brand's own profile.

• sponsoredVideos includes each sponsored content's full per-item engagement (same shape as /content-detail).

• Important caveat — only scans the most recent ~20–30 posts and only detects brands already indexed in CreatorDB. An empty sponsorList is not proof the creator has no sponsors; it's "we didn't find indexed sponsors in their recent posts."

Search (search_{platform} and search_creators_nls)

Structured search response:

• creatorList: [{ displayName, uniqueId, channelId (YT only), avatarUrl, totalSubscribers | totalFollowers }] — minimal projection; hydrate with get_*_profile for full data.

• totalResults — total matching the filter set, not just the page.

• hasNextPage + nextOffset — pagination idiom. Pass nextOffset as the next request's offset to advance.

NLS response:

• Same creatorList shape as structured search, plus a platform: "youtube" | "instagram" | "tiktok" field telling you which platform the AI routed to.

• Streamed over SSE under the hood; the MCP layer collects the final data: event and returns it as one payload.

• Dynamic pricing — typically 1–10 credits depending on input + output token count.

/usage

• records: [{ date (YYYYMMDD), requestCount, totalQuotaUsed, endpoints: { …per-endpoint counts }, platforms: { …per-platform counts }, quotaByPlatform }].

• totalQuotaUsed can be fractional (e.g. 4.49 for an NLS call).

• endpoints keys are camelCase: getYoutubeProfile, getInstagramAudience, searchYoutube, getNLS, etc. Useful for building a spend dashboard.

Common footguns

• Placeholder demographics: when CreatorDB doesn't have real audience data, /audience returns the all-zero shape (audienceGender: { maleRatio: 0, femaleRatio: 0 }, age buckets all 0.0). Treat any row where male+female=0 as missing, not as "no gender data."

• Empty sponsorList ≠ no sponsors (see above).

• relatedCreators is unranked — order is not significance. Don't slice the first N and call them "top related"; sample or rerank by your own metric.

• Freshness lag — lastDbUpdateTime is when CreatorDB last refreshed. If it's older than ~14 days, the profile may not reflect recent breakout content.

• Niche channelCount drifts — list_*_niches is updated daily; don't cache it longer than that or your "creators in X niche" count will lag reality.

• IG country is classifier-derived — unlike YT/TT (which read from self-declared profile fields), Instagram country is inferred from content. Treat it as a best-effort signal, not ground truth. Cross-check against audienceLocations and bio language when accuracy matters.

Filter reference (search tools)

Common fields across all three platforms:

• displayName — string, supports fuzzy

• uniqueId — string, exact

• country — string, ISO 3166-1 alpha-3 (e.g. "USA", "JPN", "GBR")

• mainLanguage — string, ISO 639-3 (e.g. "eng", "jpn", "zhs")

• hashtags — string (with # prefix on IG/TT)

• niches — string (use IDs from the platform's list_*_niches)

• mainAudienceLocation / mainAudienceAge / mainAudienceGender — string

• hasSponsors — boolean

Platform-specific:

• YouTube: totalSubscribers (number), topics (string from list_youtube_topics)

• Instagram / TikTok: totalFollowers (number)

Operators: >, <, = for numbers; =, in for strings; = for booleans. in takes an array of up to 100 values. pageSize max 100; filters max 10 per request.

Response envelope

Every tool returns the underlying CreatorDB V3 envelope:

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

On error, the envelope carries errorCode, error, message, and details. The MCP layer flattens that into a clean error message with a TraceId: line for support.

Development

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

Source layout:

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 (incl. search_youtube_content)
    instagram.ts           # 9 tools (incl. search_instagram_content)
    tiktok.ts              # 8 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)

Getting help

• Bugs / feature requests / new endpoint coverage: open an issue at https://github.com/CreatorDB/creatordb-mcp-server/issues

• API key / data questions: hello@creatordb.app

• Just trying to install it on your machine? See SETUP.md — a 5-minute guide aimed at end users rather than contributors.

License

MIT