# How to install Throk MCP: add Threads data tools to Claude, ChatGPT, Codex and Cursor

Throk runs an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server. Once it's set up, you can ask AI assistants such as Claude, ChatGPT, Codex and Cursor for data in plain language, for example:

> Show me the volume trend for "減脂" in Taiwan over the last 30 days, then find the 5 posts with the most likes and summarize how they open.

## Connection details

| Item | Value |
| --- | --- |
| URL | `https://premium-api.throk.ai/mcp` |
| Transport | Streamable HTTP |
| Authentication | Sign in with your Throk account (OAuth), or the header `Authorization: Bearer sk-throk-...` (the same key as the REST API) |

## Two ways to connect

- **Sign in with your Throk account** (recommended): the AI tool opens a browser. Sign in to Throk, click allow, and you're sent back to the AI tool. No API key needed. You can sign in with Google or with an email sign-in link. If you use email, open the link from the email in the same browser.
- **Use an API key**: create a key on the **API keys** page of the [developer portal](https://developer.throk.ai/dashboard) and add it to the AI tool's settings.

Both use the same account's API credits. See [Credits](#credits) below.

## Install

The [**MCP server**](https://developer.throk.ai/dashboard/mcp) (MCP 伺服器) page in the developer portal also has ready-to-copy setup examples for each AI tool.

### Claude Code

**Sign in with your Throk account**: run the command below, then type `/mcp` in Claude Code, select `throk` and sign in.

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

**Use an API key**: add `--header` to the command.

```bash
claude mcp add --transport http throk \
  https://premium-api.throk.ai/mcp \
  --header "Authorization: Bearer sk-throk-..."
```

### Claude Desktop

**Sign in with your Throk account**: add Throk as a connector.

1. Open **Settings** › **Connectors** and add a custom connector.
2. Enter `Throk` as the name and `https://premium-api.throk.ai/mcp` as the URL.
3. Click **Connect**, sign in to Throk in the browser and allow access.

**Use an API key**: pass the key through [mcp-remote](https://www.npmjs.com/package/mcp-remote). This needs Node.js installed. Add the following to `claude_desktop_config.json`, then restart Claude Desktop:

```json
{
  "mcpServers": {
    "throk": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://premium-api.throk.ai/mcp",
        "--header", "Authorization:${THROK_AUTH}"
      ],
      "env": { "THROK_AUTH": "Bearer sk-throk-..." }
    }
  }
}
```

Copy `args` exactly as shown. Only replace `sk-throk-...` in `env` with your key.

### Cursor

**Sign in with your Throk account**: put only the URL in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project), then sign in from the MCP page in Cursor's settings.

```json
{
  "mcpServers": {
    "throk": {
      "url": "https://premium-api.throk.ai/mcp"
    }
  }
}
```

**Use an API key**: add `headers`.

```json
{
  "mcpServers": {
    "throk": {
      "url": "https://premium-api.throk.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-throk-..."
      }
    }
  }
}
```

### Codex / ChatGPT desktop

The Codex app, Codex CLI and ChatGPT desktop app share the same MCP settings.

**Sign in with your Throk account**:

- **App**: go to **Plugins** › **Add** › **Create MCP App**, enter `https://premium-api.throk.ai/mcp` as the Server URL and choose OAuth for Authentication. After creating it, sign in to Throk and allow access. If you need an icon, download the [Throk icon](https://premium-api.throk.ai/icon-256.png) and upload it.
- **CLI**: add the following to `~/.codex/config.toml`, then run `codex mcp login throk`.

```toml
[mcp_servers.throk]
url = "https://premium-api.throk.ai/mcp"
```

**Use an API key**: in the app, choose Bearer token for Authentication and paste your key. For the CLI, name the environment variable that holds your key in `config.toml`:

```toml
[mcp_servers.throk]
url = "https://premium-api.throk.ai/mcp"
bearer_token_env_var = "THROK_API_KEY"
```

```bash
export THROK_API_KEY=sk-throk-...
```

### ChatGPT

On the ChatGPT website, add Throk in developer mode (Plus, Pro, Business, Enterprise and Edu plans) and sign in with your Throk account:

1. Turn on developer mode in ChatGPT settings and add a connector.
2. Enter `Throk` as the name and `https://premium-api.throk.ai/mcp` as the MCP server URL, and choose OAuth for authentication.
3. After creating it, sign in to Throk and allow access. You can then use it in your chats.

## Credits

- API keys and AI tools signed in with your Throk account share the same account's [API credits](/en/api/credits/). Each tool's cost is listed under [Available tools](#available-tools) below. You can also ask the AI assistant to call `get_balance` to check your balance at any time.
- You can still connect without an API plan, but tool calls return an error with a link to the [Buy credits](https://developer.throk.ai/dashboard/pricing) page in the developer portal.
- Credits in the [Throk web app](/en/web/plans/) (app.throk.ai) are separate from API credits and can't be used with MCP.

## Disconnect

- Tools connected with an API key: delete the key on the **API keys** page of the developer portal.
- Tools signed in with your Throk account: deleting API keys doesn't end these connections. Disconnect them on the [**MCP server**](https://developer.throk.ai/dashboard/mcp) page of the developer portal.

## Available tools

All tools are read-only.

### Search

| Tool | Purpose | Credits |
| --- | --- | --- |
| `search_posts` | Search posts by keyword (up to 25 results) | 1 credit per post (2 credits per post with details) |
| `semantic_search_posts` | Search posts from the last 30 days by meaning (up to 10 results) | 30 credits |
| `get_inspiration` | Find ideas among curated high-engagement posts (up to 10 results) | 30 credits |
| `get_hot_posts` | Trending posts (30–50 results) | From 70 credits, plus 2 credits per extra post (from 100 credits when sorted by views) |
| `get_keyword_trend` | Daily keyword volume (up to 10 keywords, 90 days) | 3 credits × keywords × days (4 credits with engagement) |

`get_inspiration` chooses the post language with `language` (all 7 codes, including English `en`). If you leave it out, it returns Chinese, Japanese and Korean posts, not English ones. For the accepted values, see [Post language](/en/api/guides/regions/#languages-by-endpoint).

### Accounts

| Tool | Purpose | Credits |
| --- | --- | --- |
| `get_user` | Account profile and recent posts | 1 credit, plus 1 credit per 5 posts |
| `get_user_top_threads` | An account's most-liked posts | From 70 credits |
| `get_user_follower_history` | An account's daily follower count (up to 365 days) | Days ÷ 3 (rounded up), minimum 1 credit |
| `get_user_interactions` | [Find who an account interacts with most](/en/api/interactions/): the accounts it trades the most replies with (up to 100 accounts, 90 days) | 30 credits for up to 10, plus 2 credits per extra account; free when there are no interactions |

### Leaderboards

| Tool | Purpose | Credits |
| --- | --- | --- |
| `get_cool_replies` | Top replies leaderboard | From 70 credits |
| `get_post_like_growth` | Viral posts (fastest-growing likes) | From 70 credits |
| `get_follower_growth` | Accounts with the fastest follower growth | From 70 credits |
| `get_follower_ladder` | Follower ladder (threshold for each tier) | 5 credits |
| `get_like_ladder` | Likes ladder (last 24 hours) | 5 credits |
| `get_power_hours` | The platform's best posting hours (last 28 days) | 5 credits |

Like the search tools, the leaderboard, ladder and power-hours tools choose the post language with `language` (default `zh`), and each language is calculated separately (`get_follower_growth` takes all 7 too). For the accepted values, see [Post language](/en/api/guides/regions/#languages-by-endpoint).

### Live data and forecasts

| Tool | Purpose | Credits |
| --- | --- | --- |
| `forecast_posts` | Forecast whether posts published 1–12 hours ago will reach view thresholds | 10 credits per post |
| `get_live_posts` | Read a post's current numbers live (any publish time) | 3 credits per post (1 credit when views are hidden) |
| `get_live_users` | Read an account's current follower count and profile live | 3 credits per account |

### Account

| Tool | Purpose | Credits |
| --- | --- | --- |
| `get_balance` | Check remaining credits | Free |

## Differences from the REST API

- **Lower result limits** keep responses compact, for example up to 25 results for `search_posts` and 10 for `semantic_search_posts`. For large volumes of data, use the REST API.
- **Media URLs and profile picture URLs are left out by default.** When you need them, add `include_media=true` on tools that support it.
- **Each call times out after 60 seconds.**
- Search rules are exactly the same as the REST API. See [Search rules](/en/api/guides/search-rules/).

For an overview of Throk MCP and plan pricing, see [Throk MCP](https://www.throk.ai/en/mcp).