> ## Documentation Index
> Fetch the complete documentation index at: https://reel25.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Reel25 to AI clients like Claude, Cursor, and VS Code

Connect Reel25 to AI clients like Claude, Cursor, and VS Code. 26 tools for tracking videos, monitoring accounts, discovering content, and running AI analysis — all through natural language.

```bash theme={null}
npx -y reel25-mcp
```

## Overview

The Reel25 MCP server exposes the same capabilities as the REST API but through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) — an open standard that lets AI assistants use external tools directly. Instead of writing API calls, you describe what you need in plain language and your AI handles the rest.

**Supported clients:** Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and any MCP-compatible client.

**Prerequisites:** Node.js 18+, an active Reel25 plan, and an API key.

## Setup

### 1. Get your API key

Create a key at [Settings → API Keys](https://app.reel25.com/settings/api-keys). See the [Authentication](/docs/authentication) page for details on key format and security.

### 2. Configure your AI client

<Tabs>
  <Tab title="Claude Desktop">
    Add to your config file:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "reel25": {
          "command": "npx",
          "args": ["-y", "reel25-mcp"],
          "env": {
            "REEL25_API_KEY": "reel25_sk_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add reel25 -- npx -y reel25-mcp
    ```

    Then set your API key:

    ```bash theme={null}
    export REEL25_API_KEY=reel25_sk_your_key_here
    ```
  </Tab>

  <Tab title="Cursor">
    Go to **Cursor Settings → MCP → Add new MCP Server**. Use command type with `npx -y reel25-mcp`. Add environment variable `REEL25_API_KEY` with your key.

    Or add to `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "reel25": {
          "command": "npx",
          "args": ["-y", "reel25-mcp"],
          "env": {
            "REEL25_API_KEY": "reel25_sk_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add to User Settings (JSON) via `Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)":

    ```json theme={null}
    {
      "mcp": {
        "inputs": [
          {
            "type": "promptString",
            "id": "reel25ApiKey",
            "description": "Reel25 API Key",
            "password": true
          }
        ],
        "servers": {
          "reel25": {
            "command": "npx",
            "args": ["-y", "reel25-mcp"],
            "env": {
              "REEL25_API_KEY": "${input:reel25ApiKey}"
            }
          }
        }
      }
    }
    ```

    Or add to `.vscode/mcp.json` in your workspace to share config with your team.
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/model_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "reel25": {
          "command": "npx",
          "args": ["-y", "reel25-mcp"],
          "env": {
            "REEL25_API_KEY": "reel25_sk_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Smithery">
    One-click install:

    ```bash theme={null}
    npx -y @smithery/cli install reel25-mcp --client claude
    ```
  </Tab>
</Tabs>

### 3. Restart your AI client

After adding the config, restart your application. The 26 Reel25 tools will appear automatically. You can verify by asking: *"What Reel25 tools do you have access to?"*

<Warning>
  **Windows users:** If you run into issues with npx, try: `cmd /c "set REEL25_API_KEY=your_key && npx -y reel25-mcp"`
</Warning>

## Available tools (26)

### Videos — free

| Tool | Description |
| - | - |
| `list_videos` | List all tracked videos. Supports pagination, filtering by platform, date range, and folder |
| `get_video` | Get full video details: current metrics (views, likes, comments, shares), music info, metadata |
| `get_video_history` | Historical performance snapshots — see how metrics changed over time |
| `track_video` | Start tracking a video by TikTok, Reels, or Shorts URL. Metrics refresh daily |
| `bulk_track_videos` | Track up to 25 videos in a single call |
| `untrack_video` | Stop tracking a video and remove it from your workspace |

### Accounts — free

| Tool | Description |
| - | - |
| `list_accounts` | List all tracked creator accounts with latest metrics |
| `get_account` | Detailed profile info — bio, follower count, total videos, engagement rate |
| `track_account` | Start tracking a creator account by URL across TikTok, Instagram, and YouTube |
| `get_account_videos` | List all tracked videos belonging to a specific creator |
| `get_account_metrics` | Detailed performance metrics — follower growth, avg engagement, posting frequency |
| `remove_account` | Stop tracking a creator account |

### Content Radar — 100 credits

| Tool | Description |
| - | - |
| `search_content` | AI-powered content discovery. Describe what you're looking for in natural language and get top-performing matching videos across platforms. Handles async polling internally (30-60 sec) |
| `get_radar_results` | Retrieve results from a previous search by ID |
| `radar_history` | List all past searches with status and result counts |

### AI Video Analysis — 5 credits

| Tool | Description |
| - | - |
| `analyze_video` | Full AI analysis: hook breakdown, content structure, CTA effectiveness, UGC assessment, engagement drivers, improvement suggestions. Handles async polling internally (15-30 sec) |
| `get_analysis` | Retrieve an existing analysis for a previously analyzed video |

### Folders — free

| Tool | Description |
| - | - |
| `list_folders` | List all folders in your workspace |
| `create_folder` | Create a new folder |
| `add_videos_to_folder` | Add tracked videos to a folder |
| `add_accounts_to_folder` | Add tracked accounts to a folder |
| `folder_analytics` | Aggregated analytics for all content in a folder — total views, avg engagement, top performers |

### Analytics and Workspace — free

| Tool | Description |
| - | - |
| `top_videos` | Top performing tracked videos ranked by views, engagement, or growth velocity |
| `growth_trends` | Follower and video count growth trends over time |
| `get_credits` | Current credit balance and usage |
| `get_workspace` | Workspace info: plan, credit limits, tracked counts, team members |

For full credit costs and plan details, see the [Credits](/docs/credits) page.

## Async tools

Two tools involve background processing: `search_content` and `analyze_video`.

Both handle polling internally — when called, the MCP server waits for results and returns the complete response. No extra steps needed from the user or agent.

* **Content Radar** (`search_content`): 30-60 seconds. The system generates search queries, scrapes platforms, filters and ranks results.
* **AI Video Analysis** (`analyze_video`): 15-30 seconds. Downloads video, runs AI models for hook, structure, CTA, and UGC analysis.

Your agent will show a natural "working on it" message during this time.

## Environment variables

| Variable | Required | Description |
| - | - | - |
| `REEL25_API_KEY` | Yes | Your API key. Starts with `reel25_sk_` |
| `REEL25_API_URL` | No | Custom API endpoint. Default: `https://api.reel25.com/api/v1` |

## Example prompts

**Discovery and Research**

* "Search for the top UGC skincare product demos on TikTok from the last week"
* "Find trending fitness content on Instagram Reels about home workouts"
* "What kind of hooks are working best in the protein supplement niche right now?"

**Tracking and Monitoring**

* "Track this TikTok video and add it to my Competitors folder: \[url]"
* "Track these 5 creator accounts and pull their engagement metrics"
* "Show me all videos I'm tracking that were posted in the last 7 days"

**Analysis and Reporting**

* "Analyze this video and tell me what makes the hook effective"
* "Show me my top 10 performing videos by engagement rate"
* "Compare growth trends for all accounts in my Influencers folder"

**Workspace Management**

* "How many credits do I have left?"
* "Create a new folder called Q2 Campaign and add these 3 videos to it"
* "What's my current plan and how many videos am I tracking?"

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not found after setup">
    Restart your AI client completely. On Claude Desktop, quit the app fully (not just close the window) and reopen.
  </Accordion>

  <Accordion title="Authentication failed">
    Double-check your API key starts with `reel25_sk_` and is set correctly. Regenerate keys at [Settings → API Keys](https://app.reel25.com/settings/api-keys) if needed.
  </Accordion>

  <Accordion title="npx command fails">
    Ensure Node.js 18+ is installed (`node --version` to check). On Windows, try the `cmd /c` wrapper mentioned in the setup section.
  </Accordion>

  <Accordion title="Tools not appearing">
    Some clients cache tool lists. Remove and re-add the MCP server config, then restart. In Cursor, click the refresh button in MCP settings.
  </Accordion>

  <Accordion title="Search or analysis timing out">
    Content Radar and AI Analysis can take 30-60 seconds. If your client has a short timeout, increase it in your MCP config.
  </Accordion>
</AccordionGroup>

## Links

* [npm package](https://www.npmjs.com/package/reel25-mcp) — `npx -y reel25-mcp`
* [GitHub](https://github.com/usnmax88/reel25-mcp) — source code and issue tracker
* [Get API Key](https://app.reel25.com/settings/api-keys)
* [API Reference](/docs/api-reference/introduction) — full REST API docs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.