Connect BlackTwist to AI Assistants (MCP Server)

BlackTwist has a built-in MCP server that lets you connect your account to AI assistants like Claude, Cursor, and other MCP-compatible tools.

Once connected, you can schedule posts, check analytics, manage drafts, and more — all through natural language.

Just tell your AI assistant what you want, and it handles the rest.

What is BlackTwist MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external apps and services.

Think of it as giving your AI assistant direct access to your BlackTwist account, so it can take actions on your behalf.

What you can do with it

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

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

Connect to Claude

You can connect BlackTwist directly to Claude Desktop, claude.ai, and Claude mobile app, as a custom connector. This uses OAuth, so no API key is needed. Claude will handle the authentication automatically.

How to connect to Claude.ai

Step 1. Open claude.ai and go to Settings > Connectors

Step 2. Click "Add custom connector"

Step 3. Enter the BlackTwist MCP server URL:

https://blacktwist.app/api/mcp

Step 4. Click Connect. Claude will redirect you to the BlackTwist login page.

Step 5. Sign in with your BlackTwist account (Google or email, the same login you normally use).

Step 6. Once signed in, you'll be redirected back to Claude. The connection is now active (if you are not redirected, click on Connect again in Claude)

That's it! You can now ask Claude things like:

• "Show me my Threads analytics for the last 7 days with insights"
• "Schedule a post for tomorrow at 9am saying: Just shipped a new feature!"
• "List my upcoming scheduled posts"

How to connect to Claude on mobile

The same steps work on the Claude mobile app (iOS and Android).

Go to Settings > Connectors > Add custom connector, enter the BlackTwist server URL, and sign in.

How it works behind the scenes

When you add BlackTwist as a custom connector, Claude automatically:

1. Discovers the BlackTwist OAuth endpoints
2. Registers itself as an authorized client
3. Redirects you to sign in with your BlackTwist account
4. Receives a secure access token to use on your behalf

Access tokens expire after 1 hour and are refreshed automatically. You won't need to re-authenticate unless you manually disconnect the integration.

Disconnecting

To revoke Claude's access, go to Settings > Integrations in claude.ai and remove the BlackTwist connector. This immediately invalidates the access token.

Connect BlackTwist MCP via API Key

For any other tools, follow these instructions:

Step 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

Step 2: Connect your AI assistant

Choose your client below and follow the instructions.

Claude Desktop

Open your Claude Desktop config file (claude_desktop_config.json) and add:

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

Replace YOUR_API_KEY with the key you copied in Step 1.

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 create/edit the .mcp.json file in your project root and add:

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

Cursor

1. Open Cursor and go to Settings > MCP
2. Add a new server with these details:
   1. Name: blacktwist
   2. Type: url
   3. Server URL: https://blacktwist.app/api/mcp
   4. Headers: Authorization: Bearer YOUR_API_KEY

Step 3: Start using it

Open your AI assistant and try any of the example prompts above. The assistant will use your BlackTwist account to carry out the action.

Managing your API keys

You can create, view, and delete API keys anytime from Settings > MCP.

• You can create multiple keys (e.g. one for Claude Desktop, one for Cursor)
• Each key shows when it was created and last used
• To revoke access, delete the key — the connection stops working immediately
• Keys are securely hashed before storage. The raw key is only shown once when you create it

Available tools

Here is the full list of actions your AI assistant can perform through the MCP connection:

Posts & Threads

• Create post — Create a single post or a multi-post thread. Schedule it for a specific date/time or save as draft. Auto-repost and follow-up settings apply automatically
• List posts — View all scheduled and published posts within a date range
• List drafts — View all saved drafts
• Get thread — View a specific thread with all its posts, media, and analytics
• Edit post — Update the text, topic, or media of a scheduled or draft post
• Edit thread — Add, remove, or reorder posts within a thread
• Delete thread — Permanently delete a thread and all its posts
• Reschedule thread — Change the scheduled date and time for a thread

Analytics

• Live metrics — Get views, likes, replies, reposts, and quotes with percentage change vs. the previous period
• Metric timeseries — Get daily data points for any metric over a date range
• Post analytics — See per-post engagement metrics (views, likes, replies, engagement rate)
• Follower growth — Track daily follower count over time
• Consistency — View a 365-day posting heatmap with current and record streaks
• Daily recap — Get yesterday's summary (new followers, posts published)
• Recommendations — Get AI-powered suggestions for best posting times and top content

Follow-up (Auto-Plug)

• Get follow-up templates — List saved follow-up templates for an account
• Get thread follow-up — Check the follow-up configuration on a specific thread
• Set thread follow-up — Attach or update an automatic promotional reply to a thread, triggered by engagement thresholds or a time delay

Scheduling & Account

• List time slots — See configured posting time slots for an account
• List providers — View all connected Threads and Bluesky accounts
• List teams — View all teams you belong to and your role in each
• Get subscription — Check your current plan, remaining post limits, and account quotas
• Get user settings — View your timezone, date format, auto-repost configuration, and more

Teams

If you use BlackTwist with a team, your AI assistant automatically works in the context of your currently active team. You can also tell it to switch by saying things like "list my posts for team X" or "use my personal account".

Team members can access paid features through their team owner's subscription — no separate plan needed.

Analytics on a paid plan

Some analytics tools (metric timeseries, post analytics, and follower growth) require a paid plan. Free-plan users can still access live metrics, consistency heatmaps, daily recaps, and recommendations.

Prompts

Prompts are 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 — weekly performance report
- content-ideas — post ideas based on your analytics (optional topic filter)
- optimize-schedule — analyze and optimize your posting schedule
- draft-review — review and improve your drafts
- monthly-recap — comprehensive monthly performance recap