Creatordb Mcp Server

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

There are two ways to connect, depending on your client:

• Local clients (Claude Code, Claude Desktop, Cursor) run the server as a subprocess via npx — see [Install (local / stdio)](#install-local--stdio).
• Web / mobile clients (Claude web, Claude mobile) can't spawn subprocesses, so they connect to the hosted HTTP endpoint — see [Remote connector (Claude web / mobile)](#remote-connector-claude-web--mobile).

Both expose the same 42 tools. Both need a CreatorDB V3 API key.

1. Prerequisites

• For the local route: Node.js 22 or newer (node -v to check)
• A CreatorDB V3 API key — get one from account settings, or ask your team admin

1. Pick a connection method below
2. Restart your MCP client so it picks up the new tools
3. Verify by running /mcp in Claude Code — creatordb should appear with status connected

Install (local / stdio)

For Claude Code, Claude Desktop, and Cursor. 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=YOUR_CREATORDB_API_KEY \
  -- 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": "YOUR_CREATORDB_API_KEY" }
    }
  }
}

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=YOUR_CREATORDB_API_KEY \
  -- 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=YOUR_CREATORDB_API_KEY

Remote connector (Claude web / mobile)

Claude in the browser and the mobile apps can't spawn local subprocesses, so they connect to the hosted HTTP endpoint instead of running npx:

URL:  https://mcp.creatordb.app/mcp
Auth: Authorization: Bearer 

In Claude web: Settings → Connectors → Add custom connector, paste the URL, and provide your V3 API key as a Bearer token. The same 42 tools appear.

Notes:

• The endpoint is stateless — your API key is read per-request from the Authorization header and never stored server-side.
• Hosted as a Firebase Cloud Function (gen 2) in asia-northeast1; source is in [functions/](./functions).
• A health check is available at (no auth, 0 credits) — returns {"status":"ok",...} if the service is up.
• Visiting in a browser shows a short landing page with these same instructions.

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

| Symptom | Cause | Fix | | --- | --- | --- | | /mcp shows creatordb as failed or connecting forever | API key missing or wrong | Re-add with claude mcp remove creatordb && claude mcp add … using the correct key | | Tools work but every response ends Credits used: undefined | Stale tool schema from an older build of this server | Restart the MCP client — clients cache the schema at session start | | Error: VALIDATION_ERROR on Instagram tools | Passing userId instead of uniqueId | IG endpoints take the handle as uniqueId. Older clients with stale schemas hit this most | | npx install fails with EACCES: permission denied | npx cache permission issue | rm -rf ~/.npm/_npx and re-run | | Error: ENOENT or cannot find dist/index.js | Method B didn't run npm run build | cd into the repo and run npm install && npm run build | | Tool descriptions seem outdated vs this README | Schema cached from an old version | claude mcp remove creatordb && claude mcp add … to force a re-fetch |

> 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](#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)

| Tool | Cost | Notes | | --- | --- | --- | | get_api_usage | 0 | Daily request counts and credit consumption by endpoint. Defaults to last 7 days; takes optional start/end Unix-ms timestamps. |

Search (4)

| Tool | Cost | Notes | | --- | --- | --- | | search_creators_nls | dynamic (token-based) | Natural-language search across all three platforms. The AI picks the platform and converts the query into filters. | | search_youtube | 1 per 10 filters | Structured filter search. Use totalSubscribers for count thresholds. | | search_instagram | 1 per 10 filters | Structured filter search. Use totalFollowers for count thresholds. | | search_tiktok | 1 per 10 filters | Structured filter search. Use totalFollowers for count thresholds. |

Filter type gotcha: numeric ops (>, `,

• API key / data questions:
• Just trying to install it on your machine? See [SETUP.md](./SETUP.md) — a 5-minute guide aimed at end users rather than contributors.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CreatorDB
• Source: CreatorDB/creatordb-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.