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

1. Generate an API Key

1. Open BlackTwist and go to Settings
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

Property	Value
URL	https://blacktwist.app/api/mcp
Auth	Bearer token (API key)
Transport	Streamable HTTP (stateless)
Protocol	MCP via JSON-RPC over HTTP POST

---

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. 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), 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).

Parameter	Type	Required	Description
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account. When set to a team, shows only providers linked to that team.

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.

Parameter	Type	Required	Description
providerId	string	Yes	Provider ID from list_providers
posts	array	Yes	Array of post objects (see below)
scheduleAt	string	No	ISO 8601 datetime. If omitted, saves as draft. Times without a timezone offset (e.g. 2025-03-15T09:00:00) are interpreted in the user's configured timezone.
autoRepost	object	No	{ enabled: boolean, delays: string[] } where delays are hours, e.g. ["168", "336"] for 7 and 14 days. If omitted, the user's default auto-repost setting is applied.
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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:

Field	Type	Required	Description
text	string	Yes	Post content
topic	string	No	Topic tag
postMedia	object[]	No	Media attachments: { mediaKey, mimeType, width, height, size, altText? }

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"
}

list_posts

List scheduled and published posts within a date range.

Parameter	Type	Required	Description
from	string	Yes	Start date (ISO 8601)
to	string	Yes	End date (ISO 8601)
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

list_drafts

List all draft posts (not yet scheduled).

Parameter	Type	Required	Description
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

get_thread

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

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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.

Parameter	Type	Required	Description
postId	string	Yes	The post ID (from get_thread)
content	string	No	New text content
topic	string	No	New topic tag. Pass null to remove the topic.
postMedia	object[]	No	Replace all media: { mediaKey, mimeType, width, height, size, altText? }. Omit to keep existing media unchanged.

At least one of content, topic, or postMedia 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.

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID
posts	array	Yes	Ordered array of posts (min 1). Order determines postOrder (0-indexed). See below.

Each post object:

Field	Type	Required	Description
id	string	No	Post ID for existing posts. Omit to create a new post in this position.
text	string	Yes	Post content
topic	string	No	Topic tag
postMedia	object[]	No	Media attachments: { mediaKey, mimeType, width, height, size, altText? }

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.

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

reschedule_thread

Change the scheduled date/time for a thread.

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID
scheduledAt	string	Yes	New datetime (ISO 8601). Times without a timezone offset are interpreted in the user's configured timezone.
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

---

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, and get_follower_growth require a paid plan (user or team owner). Free-plan users will receive: "A paid plan is required to access the analytics". 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.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
from	string	No	Start date (defaults to 7 days ago)
to	string	No	End date (defaults to now)
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
metric	enum	Yes	One of: VIEWS, LIKES, REPLIES, REPOSTS, QUOTES, ENGAGEMENT_RATE, FOLLOWERS_COUNT
from	string	Yes	Start date (ISO 8601)
to	string	Yes	End date (ISO 8601)
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

get_post_analytics

Get per-post engagement metrics for posts within a date range.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
from	string	Yes	Start date (ISO 8601)
to	string	Yes	End date (ISO 8601)
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

Returns: Up to 100 posts with views, likes, replies, reposts, quotes, engagementRate.

get_follower_growth

Get daily follower count over time.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
from	string	Yes	Start date (ISO 8601)
to	string	Yes	End date (ISO 8601)
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

Returns: Daily followers data points and totalGrowth.

get_consistency

Get a 365-day posting consistency heatmap.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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

get_daily_recap

Get yesterday's summary.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

Returns: date, newFollowers, postsCount.

get_recommendations

Get posting recommendations based on your analytics patterns.

Parameter	Type	Required	Description
providerUserId	string	Yes	Provider user ID
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

Returns: bestPostingHoursUtc, topPerformingPosts, currentStreak, recordStreak.

---

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.

Parameter	Type	Required	Description
userProviderId	string	Yes	Provider id from list_providers
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account. Scopes which team members' templates are included.

get_thread_follow_up

Get the follow-up configuration for a specific thread.

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID

set_thread_follow_up

Set or update the follow-up for a thread.

Parameter	Type	Required	Description
threadId	string	Yes	The thread ID
isEnabled	boolean	Yes	Enable/disable the follow-up
text	string	No	Follow-up reply text
images	string[]	No	Image URLs
delayTimeMinutes	number	No	Time delay trigger (minutes)
delayTimeMinutesEnabled	boolean	No	Enable time delay trigger
numberOfLikes	number	No	Likes threshold
numberOfLikesEnabled	boolean	No	Enable likes trigger
numberOfReplies	number	No	Replies threshold
numberOfRepliesEnabled	boolean	No	Enable replies trigger
numberOfReposts	number	No	Reposts threshold
numberOfRepostsEnabled	boolean	No	Enable reposts trigger
autoPlugMedia	object[]	No	Media attachments: { mediaKey, mimeType, width, height, size }

---

Scheduling

list_time_slots

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

Parameter	Type	Required	Description
providerId	string	Yes	Provider id from list_providers
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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

---

Account

get_subscription

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

Parameter	Type	Required	Description
teamId	string	No	Team ID. If not provided, uses the active team. Pass "personal" for the personal account.

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

---

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.

---

Technical Details

• Endpoint: POST /api/mcp (JSON-RPC)
• Transport: Streamable HTTP (stateless, no session management)
• Auth: API key validated via Authorization: Bearer <key> header
• Protocol: MCP via JSON-RPC over HTTP POST

---

License

MIT