BlackTwist MCP Server

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), edit_post / edit_thread / get_thread_follow_up / set_thread_follow_up (thread-based access handles team auth internally via userCanAccessThread).

Subscription access: Analytics