# CreatorDB MCP Server

An MCP (Model Context Protocol) server that provides access to the CreatorDB Headless API V3 for influencer marketing data across Instagram, YouTube, and TikTok.

## Features

This MCP server exposes 31 tools covering all CreatorDB API V3 endpoints:

### General Operations
- **get_api_usage** - Get API usage statistics and quota consumption

### Instagram (11 tools)
- **instagram_get_profile** - Complete profile with metadata, stats, hashtags, niches
- **instagram_get_contact** - Contact information (emails)
- **instagram_get_content_detail** - Detailed content information
- **instagram_get_performance** - Engagement rates, likes, comments, consistency scores
- **instagram_get_performance_history** - Historical performance data
- **instagram_get_sponsorship** - Sponsored content information
- **instagram_get_audience** - Demographics: country, gender, age breakdown
- **instagram_search** - Advanced search with 10+ filter types
- **instagram_natural_language_search** - AI-powered natural language queries
- **instagram_get_niches** - All available niches with creator counts

### YouTube (11 tools)
- **youtube_get_profile** - Complete profile with pricing estimates, topics, niches
- **youtube_get_contact** - Contact information
- **youtube_get_content_detail** - Video details and performance
- **youtube_get_performance** - Views, engagement, content statistics
- **youtube_get_performance_history** - Historical performance data
- **youtube_get_sponsorship** - Sponsored content data
- **youtube_get_audience** - Audience demographics
- **youtube_search** - Advanced search with filters
- **youtube_natural_language_search** - AI-powered search
- **youtube_get_topics** - Content categories
- **youtube_get_niches** - Available niches

### TikTok (9 tools)
- **tiktok_get_profile** - Complete profile with follower stats, hashtags, niches
- **tiktok_get_contact** - Contact information
- **tiktok_get_content_detail** - Video details
- **tiktok_get_performance** - Engagement metrics
- **tiktok_get_performance_history** - Historical data
- **tiktok_get_audience** - Audience demographics
- **tiktok_search** - Advanced search with filters
- **tiktok_natural_language_search** - AI-powered search
- **tiktok_get_niches** - Available niches

## Installation

```bash
# Clone or copy this directory
cd creatordb-mcp

# Install dependencies
npm install

# Build the TypeScript
npm run build
```

## Configuration

Set your CreatorDB API key as an environment variable:

```bash
export CREATORDB_API_KEY="your-api-key-here"
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "creatordb": {
      "command": "node",
      "args": ["/path/to/creatordb-mcp/dist/index.js"],
      "env": {
        "CREATORDB_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Usage with Claude Code

```bash
# Add the MCP server
claude mcp add creatordb -- node /path/to/creatordb-mcp/dist/index.js

# Or with environment variable
CREATORDB_API_KEY=your-key claude mcp add creatordb -- node /path/to/creatordb-mcp/dist/index.js
```

## Development

```bash
# Run in development mode (without building)
npm run dev

# Build for production
npm run build

# Run built version
npm start
```

## API Details

- **Base URL**: `https://apiv3.creatordb.app`
- **Authentication**: API key via `api-key` header
- **Response format**: JSON with `success`, `data`, `traceId`, `timestamp` fields

## Example Tool Calls

### Search Instagram creators with filters
```json
{
  "name": "instagram_search",
  "arguments": {
    "filters": [
      { "filterName": "totalFollowers", "op": ">", "value": 100000 },
      { "filterName": "country", "op": "=", "value": "USA" },
      { "filterName": "niches", "op": "in", "value": ["fashion_Lifestyle"] }
    ],
    "pageSize": 20,
    "offset": 0,
    "sortBy": "totalFollowers",
    "desc": true
  }
}
```

### Natural language search
```json
{
  "name": "instagram_natural_language_search",
  "arguments": {
    "query": "fashion influencers in USA with over 100k followers",
    "pageSize": 20,
    "offset": 0
  }
}
```

### Get Instagram creator profile
```json
{
  "name": "instagram_get_profile",
  "arguments": {
    "uniqueId": "instagram"
  }
}
```

### Get YouTube creator profile
```json
{
  "name": "youtube_get_profile",
  "arguments": {
    "channelId": "UCBR8-60-B28hp2BmDPdntcQ"
  }
}
```

### Get TikTok creator audience demographics
```json
{
  "name": "tiktok_get_audience",
  "arguments": {
    "uniqueId": "tiktok"
  }
}
```

### Search YouTube creators by topic
```json
{
  "name": "youtube_search",
  "arguments": {
    "filters": [
      { "filterName": "topics", "op": "in", "value": ["gaming_Gaming"] },
      { "filterName": "totalSubscribers", "op": ">", "value": 1000000 }
    ],
    "pageSize": 10,
    "offset": 0,
    "sortBy": "totalSubscribers",
    "desc": true
  }
}
```

## Filter Reference

### Common Filter Fields (all platforms)
- `displayName` - Creator display name (string, supports fuzzy search)
- `country` - Country code in ISO 3166-1 alpha-3 (e.g., "USA", "GBR", "TWN")
- `mainLanguage` - Primary language in ISO 639-3 (e.g., "eng", "zht")
- `niches` - Content niches (array of strings)
- `isVerified` - Verified account (boolean)
- `hasSponsors` - Has sponsored content (boolean)

### Instagram-specific
- `totalFollowers` - Follower count (number)
- `avgEngagementRate` - Average engagement rate (number, 0-1)

### YouTube-specific
- `totalSubscribers` - Subscriber count (number)
- `topics` - Content topics (array of strings)

### TikTok-specific
- `totalFollowers` - Follower count (number)

### Filter Operators
- `=` - Equals (strings, booleans)
- `>` - Greater than (numbers)
- `<` - Less than (numbers)
- `in` - Value in array (arrays of strings)

## Troubleshooting

### API Key Issues
- Ensure `CREATORDB_API_KEY` is set correctly
- Check if the key has sufficient credits
- Header format is `api-key: your-key` (not Bearer token)

### Common Errors
- `429` - Quota exceeded or rate limited
- `400` - Invalid parameters (check filter format)

## License

MIT