BlackTwist MCP Server

The BlackTwist MCP (Model Context Protocol) server allows AI assistants like Claude, Cursor, and other MCP-compatible clients to interact with your BlackTwist account — creating posts, checking analytics, managing drafts, and more.

Quick Start

There are two ways to connect to the BlackTwist MCP server: OAuth (recommended for claude.ai) or API Key (for desktop clients and CLI tools).

Option A: Connect via OAuth (claude.ai)

If you're using claude.ai as a custom connector, OAuth is the easiest option — no API key needed.

1. Go to claude.ai > Settings > Integrations (or add a custom connector)
2. Enter the MCP server URL: https://blacktwist.app/api/mcp
3. Claude will automatically discover the OAuth endpoints, register itself, and redirect you to sign in with your BlackTwist account
4. Once signed in, the connection is established — Claude can now use your BlackTwist account

OAuth tokens refresh automatically, so you won't need to re-authenticate unless you revoke access.

Option B: Connect via API Key

For Claude Desktop, Claude Code, Cursor, and other MCP clients that don't support OAuth, use an API key.

1. Generate an API Key

1. Open BlackTwist and go to Settings (gear icon)
2. Click the MCP tab in the sidebar
3. Click Create API Key, give it a name (e.g. "Claude Desktop"), and click Create Key
4. Copy the key immediately — it won't be shown again

2. Configure Your MCP Client

Add the following to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
  "blacktwist": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY"
    }
  }
}

You need node.js v22, if you are using nvm be sure to use the correct version:

{
  "blacktwist": {
    "command": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin/npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY",
      "PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/usr/bin:/bin",
      "NODE_PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/lib/node_modules"
    }
  }
}

Claude Code

Run in the terminal:

claude mcp add --transport http blacktwist https://blacktwist.app/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

Or edit the file .mcp.json in project root:

{
  "mcpServers": {
    "blacktwist": {
      "type": "url",
      "url": "https://blacktwist.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor (Settings > MCP):

• Name: blacktwist
• Type: url
• Server URL: https://blacktwist.app/api/mcp
• Headers: Authorization: Bearer YOUR_API_KEY

3. Start Using It

Once connected, you can ask your AI assistant things like:

• "List my connected social accounts"
• "Schedule a post on Threads for tomorrow at 9am saying: Just shipped a new feature!"
• "Edit my latest draft to say: Updated copy with better hook"
• "Add a second post to my thread about product launches"
• "Show me my analytics for the last 7 days"
• "What are my best posting times?"
• "List my upcoming scheduled posts"

Server Details

Team Context (teamId)

Most tools accept an optional teamId parameter to scope operations to a specific team.

Behavior:

1. If teamId is a team ID, the tool operates in that team's context (membership is verified).
2. If teamId is "personal", the tool operates in personal mode (user's own data only, no team).
3. If teamId is omitted, the tool falls back to the user's currently active team (from user settings). If no team is active, this is equivalent to "personal".

Tools that support teamId: list_providers, list_posts, list_drafts, create_post, get_thread, delete_thread, reschedule_thread, list_time_slots, get_subscription, get_follow_up_templates, and all analytics tools.

Tools without teamId: list_teams (lists all teams), get_user_settings (personal settings), list_viral_templates / list_viral_template_categories (account-wide content library), edit_post / edit_thread / get_thread_follow_up / set_thread_follow_up (thread-based access handles team auth internally via userCanAccessThread).

Subscription access: Analytics tools that require a paid plan will check the user's own subscription first. If the user doesn't have one, the system also checks whether any team owner the user belongs to has an active plan. This means team members can access paid features through their team owner's subscription.

Available Tools

Providers

list_providers

List all connected social media accounts (Threads and Bluesky).

Returns: Array of providers with id, provider, providerUserId, providerUsername, displayName, profilePicture.

Note: Many other tools require a providerId (the id field) or providerUserId from this response.

Teams

list_teams

List all teams the user belongs to, including their role and which team is currently active. Always includes a "personal" entry representing the user's personal (non-team) account.

Parameters: None

Returns: Array of teams with id, name, role (OWNER, ADMIN, MEMBER, GUEST), isActive, createdAt.

The personal entry has id: "personal" and is marked isActive: true when no team is currently selected.

Note: The team id can be passed as teamId to other tools (list_posts, list_drafts, create_post, etc.). Pass "personal" to explicitly use the personal account. When teamId is omitted, those tools automatically use the user's currently active team.

Posts & Threads

create_post

Create a new post or thread. A thread is multiple posts linked together.

Default behaviors applied automatically:

• Auto-repost: If autoRepost is not provided and the user has auto-repost enabled in settings, the default delays are applied to the first post.
• Follow-up (auto-plug): If the provider has a default follow-up template enabled, it is automatically copied and attached to the thread. The response includes autoPlugApplied: true when this happens.
• Timezone: Times without an offset are interpreted in the user's notificationsTimezone setting.

Each post object:

Example — single post:

{
  "providerId": "clx...",
  "posts": [{ "text": "Hello world!" }],
  "scheduleAt": "2025-03-15T09:00:00"
}

Example — thread:

{
  "providerId": "clx...",
  "posts": [
    { "text": "Thread time! Here's what I learned this week 🧵" },
    { "text": "1/ First lesson: consistency beats perfection" },
    { "text": "2/ Second lesson: engage with your community daily" }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

Media Attachments

Tools that accept media (create_post, edit_post, edit_thread, set_thread_follow_up) let you attach images and videos via public URLs. The server downloads, validates against Threads specs, and uploads them automatically.

Each media object:

Threads image specs:

• Formats: JPEG, PNG
• Max file size: 8 MB
• Max aspect ratio: 10:1

Threads video specs:

• Formats: MP4, MOV
• Max file size: 1 GB
• Duration: up to 5 minutes
• Max width: 1920px

Example — post with an image:

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Check out this view!",
      "media": [
        {
          "url": "https://example.com/photo.jpg",
          "altText": "Sunset over the mountains"
        }
      ]
    }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

Spoilers (Threads only)

Spoilers allow you to hide portions of text or media behind a blur effect on Threads. Viewers tap to reveal the hidden content.

Text spoilers are defined as an array of character ranges:

• Maximum 10 spoiler ranges per post
• Ranges refer to character positions in the text field

Media spoilers are a single boolean flag per post. When isSpoilerMedia is true, all media (images and videos) in the post is blurred until the viewer taps to reveal.

Text and media spoilers are independent — a post can have both, either, or neither.

Example — post with text spoiler:

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "The winner is John!",
      "spoilerRanges": [{ "offset": 14, "length": 5 }]
    }
  ]
}

Example — post with media spoiler:

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Spoiler alert! Check the image",
      "media": [{ "url": "https://example.com/reveal.jpg" }],
      "isSpoilerMedia": true
    }
  ]
}

In responses (list_posts, list_drafts, get_thread), each post includes:

• spoilerRanges: array of { offset, length } (empty if no text spoilers)
• isSpoilerMedia: boolean (true if media is spoilered)

list_posts

List scheduled and published posts within a date range.

list_drafts

List all draft posts (not yet scheduled).

get_thread

Get a specific thread with all its posts, media, and analytics.

edit_post

Edit the text content, topic, or media of a single post. Only posts with status READY (drafts or scheduled) can be edited — published, processing, or failed posts are rejected. Use get_thread first to retrieve post IDs.

At least one of content, topic, media, spoilerRanges, or isSpoilerMedia must be provided.

Returns: postId, threadId, updated (object indicating which fields were changed).

Example — update text:

{
  "postId": "clx...",
  "content": "Updated post content"
}

Example — update text and clear topic:

{
  "postId": "clx...",
  "content": "New content",
  "topic": null
}

edit_thread

Edit a thread by adding, removing, or reordering its posts. Provide the full desired list of posts — existing posts (with id) are updated, new posts (without id) are created, and existing posts not in the list are removed. Only threads where all posts have status READY can be edited.

Each post object:

New posts inherit scheduledAt, provider, providerUserId, and teamId from the existing thread.

Returns: threadId, postsUpdated, postsCreated, postsDeleted, totalPosts.

Example — reorder and add a post:

{
  "threadId": "abc123",
  "posts": [
    { "id": "existing-post-2", "text": "Now this is first" },
    { "id": "existing-post-1", "text": "Now this is second" },
    { "text": "Brand new third post" }
  ]
}

Example — remove a post (omit it from the list):

{
  "threadId": "abc123",
  "posts": [{ "id": "existing-post-1", "text": "Keep only this one" }]
}

delete_thread

Permanently delete a thread and all its posts.

reschedule_thread

Change the scheduled date/time for a thread.

Analytics

All analytics tools require a providerUserId (from list_providers) and accept an optional teamId to scope access.

Paid plan required: get_metric_timeseries, get_post_analytics, get_follower_growth, and get_best_time_to_post require a paid plan (user or team owner). Free-plan users will receive: "A paid plan is required to access the analytics. Subscribe at https://blacktwist.app#pricing". The remaining tools (get_live_metrics, get_consistency, get_daily_recap, get_recommendations) are available on all plans.

Date ranges: The from and to dates are both inclusive. For example, from: "2026-03-01" and to: "2026-03-08" includes all data from March 1 through the end of March 8.

get_live_metrics

Get engagement metrics with percentage change vs. the previous period.

Returns: views, likes, replies, reposts, quotes — each with value and percentageChange.

get_metric_timeseries

Get daily data points for a specific metric over a date range.

get_post_analytics

Get per-post engagement metrics for posts within a date range. Each post also carries its thread continuation parts (self-replies), so multi-post threads are returned in full.

Returns: Up to 100 posts with views, likes, replies, reposts, quotes, engagementRate. Each post also includes a thread array of its continuation parts, reconstructed from the user's self-replies — so a multi-post thread comes back with all of its posts. Each part has replyId, text (truncated to 200 characters), permalink, timestamp, partOrder (starting at 2; the root post is part 1), and its own analytics (views, likes, replies, reposts, quotes, engagementRate). Single posts return an empty thread. Pass includeThreadParts: false to skip reconstruction entirely and return empty thread arrays.

get_follower_growth

Get daily follower count over time.

Returns: Daily followers data points and totalGrowth.

get_consistency

Get a 365-day posting consistency heatmap.

Returns: days (array of { date, count }), totalPosts, daysWithPosts, currentStreak, recordStreak.

get_daily_recap

Get yesterday's summary.

Returns: date, newFollowers, postsCount.

get_recommendations

Get posting recommendations based on your analytics patterns.

Returns: bestPostingHoursUtc, topPerformingPosts, currentStreak, recordStreak.

get_best_time_to_post

Get the best times to post based on historical engagement over the last 10 weeks. Mirrors the "Best time to post" analytics chart — engagement bucketed by hour of day, both averaged across the whole week and broken down per day of the week. Hours are reported in the user's own timezone.

Active subscription required: This tool requires an active subscription — the user must have their own paid plan, or be part of a team whose owner has an active subscription. Otherwise it returns: "The best time to post requires an active subscription. You need your own paid plan, or to be part of a team whose owner has an active subscription. Subscribe at https://blacktwist.app#pricing"

Timezone: Resolved automatically server-side from the user's notificationsTimezone setting (defaulting to UTC). MCP callers normally cannot know the user's timezone, so they should leave timezoneOffset unset and let it be derived.

Returns: provider, timezone (IANA name, or "custom" when an override offset is used), timezoneOffsetMinutes, timezoneInfo (a human-readable note naming the timezone used and linking to https://blacktwist.app/write?settings=notifications so the user can correct it if it's wrong), and (depending on view) averageView (bestHours + 24 hourly averageEngagement values across the whole week) and dailyView (7 days, each with dayName, bestHour, and 24 hourly averageEngagement values).

Follow-Up (Auto-Plug)

The follow-up system automatically replies to your post after it reaches engagement thresholds (likes, replies, reposts) or a time delay.

get_follow_up_templates

List saved follow-up templates for a provider.

get_thread_follow_up

Get the follow-up configuration for a specific thread.

set_thread_follow_up

Set or update the follow-up for a thread.

Scheduling

list_time_slots

List configured posting time slots for a provider. Time slots define preferred scheduling times.

Returns: Array of { timeSlotHour, timeSlotMinute, weekDays } where weekDays is [0-6] (0 = Sunday).

Viral Templates

Browse the library of viral post templates extracted from high-performing posts. Each template includes the structure, usage instructions, and the original example post with its engagement metrics.

Paid plan required: Both tools below require an active paid plan (user-owned plan, Lifetime Deal, or membership in a workspace whose owner has a paid plan). Free-plan users will receive: "A paid plan is required to access viral post templates".

list_viral_templates

List viral post templates with filtering, free-text search, sorting, and pagination.

Returns: { templates, categories, totalCount, page, pageSize }.

Each template:

list_viral_template_categories

List all available template categories with the number of templates in each. Useful as a discovery step before calling list_viral_templates with a category filter.

Parameters: None

Returns: { categories: [{ category, templateCount }] }, ordered alphabetically by category.

Account

get_subscription

Get your current plan, remaining post limits, and account quotas.

Returns: planType, planName, isFreePlan, remainingPosts, limits (maxTeams, maxMembers, maxAccounts).

get_user_settings

Get your user settings including timezone, date format, and auto-repost config.

Parameters: None

Returns: notificationsTimezone, dateFormat, autoRepostEnabled, autoRepostDelays, and more.

Common Workflows

Schedule a post at your next free time slot

1. list_providers → get your provider ID
2. list_time_slots → find available slots
3. create_post → schedule with the next slot time

Check weekly performance

1. list_providers → get your provider user ID
2. get_live_metrics → see this week vs. last week
3. get_recommendations → get improvement suggestions

Edit an existing post

1. get_thread → retrieve the thread and its post IDs
2. edit_post → update the text, topic, or media of a specific post

Add a post to an existing thread

1. get_thread → retrieve current posts with their IDs
2. edit_thread → pass all existing posts (with IDs) plus the new post (without ID)

Create a post with follow-up

1. create_post → create and schedule the post (returns threadId)
2. set_thread_follow_up → attach a promotional reply

Prompts

The MCP server includes built-in prompts — reusable templates that guide your AI assistant through multi-step workflows. In Claude Desktop, access them by typing / in the chat. In Claude Code, run claude prompts to list them.

weekly-report

Generate a weekly performance report with engagement metrics, top posts, follower growth, and recommendations.

Arguments:

Example: "Run the weekly-report prompt for my Threads account"

content-ideas

Generate post ideas based on your best-performing content and posting patterns.

Arguments:

Example: "Give me content ideas about marketing"

optimize-schedule

Analyze your posting patterns and suggest an optimal posting schedule for the week.

Arguments:

Example: "Help me optimize my posting schedule"

draft-review

Review your current drafts and get suggestions to improve them before publishing.

Arguments: None

Example: "Review my drafts and tell me how to improve them"

monthly-recap

Generate a comprehensive monthly recap with key metrics, top posts, and growth trends.

Arguments:

Example: "Generate my monthly recap"

API Key Management

• Create keys: Settings > MCP > Create API Key
• View keys: Settings > MCP (shows prefix, creation date, last used)
• Delete keys: Click the trash icon next to any key
• Endpoint: GET/POST/DELETE /api/user/mcp-keys

Keys are hashed with SHA-256 before storage. The raw key is only shown once at creation time.

Authentication

The MCP server supports two authentication methods. Both use the Authorization: Bearer <token> header.

OAuth 2.1 (for claude.ai and OAuth-capable clients)

The server implements the MCP Authorization specification with OAuth 2.1 and PKCE (S256). OAuth-capable clients like claude.ai handle the flow automatically.

OAuth endpoints:

How it works:

1. The client discovers the OAuth endpoints via the well-known metadata
2. The client registers itself using dynamic client registration
3. The user is redirected to sign in with their BlackTwist account (uses the existing BlackTwist login)
4. After sign-in, an authorization code is issued and exchanged for access + refresh tokens
5. Access tokens expire after 1 hour and are refreshed automatically using the refresh token (30-day lifetime)

API Keys (for desktop clients and CLI tools)

API keys are static tokens prefixed with bt_mcp_. They don't expire by default and are suitable for clients that don't support OAuth (Claude Desktop, Cursor, Claude Code CLI).

See API Key Management for how to create and manage keys.

Technical Details

• Endpoint: POST /api/mcp (JSON-RPC)
• Transport: WebStandardStreamableHTTPServerTransport from @modelcontextprotocol/sdk
• Mode: Stateless (no session management)
• Auth: OAuth 2.1 with PKCE (S256) or API key via Authorization: Bearer <key> header
• Unauthenticated discovery: initialize and tools/list can be called without authentication, so MCP registries (e.g. Glama) can inspect available tools
• Rate limiting: Authenticated requests are rate-limited to 60 req/min per IP. Unauthenticated discovery requests are limited to 10 req/min per IP.
• Source code: src/libs/mcp/ (server, auth, oauth, tools), src/app/api/mcp/ (route handler, OAuth endpoints)