# CheckViral MCP Server

> Connect Claude, ChatGPT, Codex, Cursor and other AI assistants to CheckViral. Let your AI agents do TikTok content research, including video breakdowns, creator analysis and posts audit.

Source: https://checkviral.ai/docs/mcp/

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open standard that lets AI apps call tools provided by other services. CheckViral's server has 12 tools and uses OAuth for sign-in, so there is no API key to create, copy or rotate.

## Quick start

| Setting | Value |
| --- | --- |
| Server URL | `https://api.checkviral.ai/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE, in your browser |
| API key | Not needed |
| Price | Searching and reading are free. A post analysis costs 1 credit, a creator analysis 2 credits |

1. Add `https://api.checkviral.ai/mcp` as a custom connector or remote MCP server in your AI app. Exact steps for each app are in [Connect your AI app](#connect-your-ai-app).
2. The app opens a CheckViral page in your browser. Sign in, or [create a free account](https://app.checkviral.ai/signup) if you don't have one.
3. Check which app is asking for access and click **Approve**.
4. Ask a question, for example: "Find fitness TikToks with exceptional engagement and summarize their hooks."

## Connect your AI app

Every app uses the same server URL and the same browser sign-in. Find yours below.

### Claude

Works on claude.ai and in the Claude desktop app.

1. In Claude, open **Settings → Connectors** and click **Add custom connector**.
2. Enter `CheckViral` as the name, paste `https://api.checkviral.ai/mcp` as the URL and save.
3. Click **Connect**, sign in to CheckViral if asked and approve access.

On Team and Enterprise plans, an owner may have to add the connector for the organization first. If Claude doesn't use CheckViral in a chat, check that the connector is switched on in the chat's tools menu.

### Claude Code

Add the server:

```bash
claude mcp add --transport http checkviral https://api.checkviral.ai/mcp
```

Then run `/mcp` inside Claude Code, select **checkviral** and sign in in the browser window that opens.

The command above adds CheckViral to the current project only. Add `--scope user` to make it available in all your projects.

### ChatGPT

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**. On Business and Enterprise workspaces an admin may have to allow it first, which is the usual reason the option is missing.
2. Create a connector, name it `CheckViral`, paste `https://api.checkviral.ai/mcp` and choose **OAuth** for authentication.
3. Sign in to CheckViral and approve access.

Some ChatGPT plans allow only read-only tools. You can still search the library and read analyses and your account, but starting new analyses needs write access.

### Codex

Add the server and sign in:

```bash
codex mcp add checkviral --url https://api.checkviral.ai/mcp
codex mcp login checkviral
```

The second command opens your browser to sign in. Codex gives up on a tool call after 60 seconds by default. CheckViral always answers within about 45 seconds, so the default setting works.

### Cursor

[Add CheckViral to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=checkviral&config=eyJ1cmwiOiJodHRwczovL2FwaS5jaGVja3ZpcmFsLmFpL21jcCJ9) with one click, or add it to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project) yourself:

```json
{
  "mcpServers": {
    "checkviral": {
      "url": "https://api.checkviral.ai/mcp"
    }
  }
}
```

Then open Cursor's settings, find **checkviral** in the MCP section, click **Connect**, sign in to CheckViral and approve access.

### VS Code

Add the server to `.vscode/mcp.json` in your project, or run **MCP: Add Server** from the Command Palette and choose HTTP:

```json
{
  "servers": {
    "checkviral": {
      "type": "http",
      "url": "https://api.checkviral.ai/mcp"
    }
  }
}
```

When VS Code starts the server, it asks you to sign in. Allow it, then approve access in the browser.

### Other MCP clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect. Give it `https://api.checkviral.ai/mcp` and it will find the sign-in flow by itself. Many clients use this config shape:

```json
{
  "mcpServers": {
    "checkviral": {
      "url": "https://api.checkviral.ai/mcp"
    }
  }
}
```

If a client only supports local (stdio) servers, connect through [mcp-remote](https://www.npmjs.com/package/mcp-remote). It runs on your computer and handles the browser sign-in:

```json
{
  "mcpServers": {
    "checkviral": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.checkviral.ai/mcp"]
    }
  }
}
```

## Tools reference

You don't call these tools yourself. Your AI app picks them based on what you ask. This reference shows what each tool can do, so you know what to ask for and can follow what the assistant is doing.

| Tool | Cost | What it does |
| --- | --- | --- |
| `search_analyzed_posts` | Free | Search the public library of analyzed TikTok posts |
| `get_post_analysis` | Free | Get the AI breakdown of one post |
| `get_post_analysis_section` | Free | Get full sections of a breakdown, word for word |
| `search_creators` | Free | Search analyzed TikTok creators |
| `get_creator` | Free | Get one creator's profile and stats |
| `get_creator_top_posts` | Free | Get a creator's best-performing recent posts |
| `analyze_tiktok_post` | 1 credit | Start a new analysis of a TikTok post |
| `analyze_tiktok_creator` | 2 credits | Analyze a whole TikTok creator account |
| `get_analysis_job` | Free | Wait for and collect the result of an analysis |
| `list_my_analyses` | Free | List the posts and creators you have analyzed |
| `retry_analysis_job` | 1 or 2 credits | Run a failed analysis again |
| `get_my_account` | Free | Show your credits, plan and prices |

## Use cases and example prompts

You don't need to name tools in your prompts. Describe what you want and the assistant picks the right tools. These prompts work in any connected app.

### Research what works in your niche

The library is free to search, so start there before spending credits. It's a good way to find hook patterns, formats and engagement benchmarks in a niche.

```prompt
Search CheckViral for fitness TikToks with exceptional engagement. Group their hooks by type and tell me which patterns show up most often.
```

```prompt
Find analyzed slideshow posts about personal finance. What do the best-performing ones have in common?
```

Tools used: `search_analyzed_posts`, `get_post_analysis`.

### Break down a viral video

Paste any TikTok link. If the post isn't in the library yet, the assistant starts a new analysis and reports back in about a minute.

```prompt
Analyze this TikTok and explain why it performed so well: https://www.tiktok.com/@creator/video/1234567890
```

```prompt
Break down this post and give me three ways to adapt its hook for my skincare brand: https://vt.tiktok.com/ZS1234567/
```

```prompt
Show the TikToks I analyzed recently and tell me which one had the strongest hook.
```

Tools used: `analyze_tiktok_post`, `get_analysis_job`, `get_post_analysis_section`, `list_my_analyses`.

### Audit a creator or competitor

```prompt
Analyze @creator on TikTok. Which of their recent posts performed best, what formats do they rely on, and how does their engagement compare to accounts of a similar size?
```

Tools used: `analyze_tiktok_creator`, `get_creator_top_posts`.

### Find creators to work with

```prompt
Find beauty creators on CheckViral with good or exceptional engagement and sort them by follower count.
```

Tools used: `search_creators`, `get_creator`.

### Write hooks and scripts from proven posts

```prompt
Look at five analyzed cooking TikToks with exceptional engagement. Based on what their hooks do, write three hook options and a 30-second script for my video about one-pan dinners.
```

Tools used: `search_analyzed_posts`, `get_post_analysis`.

### Improve your own posts

```prompt
Analyze my latest TikTok: https://www.tiktok.com/@myaccount/video/1234567890. List its weak points with fixes, then rewrite the first three seconds.
```

Tools used: `analyze_tiktok_post`, `get_analysis_job`.

### Track your analyses and credits

```prompt
How many CheckViral credits do I have left, and when does my monthly allowance renew?
```

Tools used: `get_my_account`.

## Troubleshooting

**The assistant says an analysis is still running.** Post analyses take about a minute, which is longer than a single tool call waits. A good assistant calls `get_analysis_job` again on its own. If yours stops, ask it to "check the CheckViral analysis again". The finished analysis also appears in the CheckViral web app.

**"Not enough credits".** Ask the assistant how many credits you have left, then top up or upgrade on your [account page](https://app.checkviral.ai/account).

**"Rate limit reached".** Wait the number of seconds given in the message, then try again.

**The app asks you to sign in again.** Sign-ins expire after 30 days without use. Approve access again and the app reconnects.