# OpenTweet MCP Server

[![npm version](https://img.shields.io/npm/v/@opentweet/mcp-server)](https://www.npmjs.com/package/@opentweet/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Post, schedule, and thread on X (Twitter), Bluesky and LinkedIn from Claude, Cursor, ChatGPT, Windsurf, or any MCP client. 44 tools covering posts, threads, cross-posting, scheduling, CSV import, long-form Articles, an evergreen queue, analytics, AI media generation, DM campaigns, and multi-account management.

No X developer account, no OAuth app setup, no pay-per-call API billing. OpenTweet owns the X connection; your agent gets simple tools.

<p align="center">
  <img src="icon.png" alt="OpenTweet" width="128" height="128">
</p>

## Quick start: hosted server (recommended)

Nothing to install. Point your MCP client at the hosted Streamable HTTP endpoint:

```
https://mcp.opentweet.io/mcp
```

**Claude Code, one command:**

```bash
claude mcp add --transport http opentweet \
  https://mcp.opentweet.io/mcp \
  --header "Authorization: Bearer ot_your_api_key"
```

**Or any MCP client config (Claude, Cursor, Windsurf, ChatGPT connectors):**

```json
{
  "mcpServers": {
    "opentweet": {
      "type": "streamable-http",
      "url": "https://mcp.opentweet.io/mcp",
      "headers": { "Authorization": "Bearer ot_your_api_key" }
    }
  }
}
```

Get your API key (prefix `ot_`) at [opentweet.io/developer](https://opentweet.io/developer). Connect your X account once in the dashboard; the key covers everything else.

## Other install options

### Claude Desktop extension (one click)

Download the `.mcpb` extension from [opentweet.io/claude-desktop](https://opentweet.io/claude-desktop) and double-click it. Your API key is stored in the OS keychain.

To build a bundle from this repo:

```bash
cd mcp-server
npm run build:mcpb
```

That compiles TypeScript, installs production dependencies only, and writes `opentweet-<package.json version>.mcpb`. Bump the version in both `package.json` and `manifest.json` before building, otherwise the output overwrites the bundle already in the repo. The tool list in `manifest.json` is what Claude Desktop shows before install, so keep it in step with the tools the server registers.

### Local via npm

```bash
npx -y @opentweet/mcp-server install   # interactive installer, detects your client
```

Or add manually:

```json
{
  "mcpServers": {
    "opentweet": {
      "command": "npx",
      "args": ["-y", "@opentweet/mcp-server"],
      "env": { "OPENTWEET_API_KEY": "ot_your_api_key" }
    }
  }
}
```

Config file locations:
- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Cursor:** `~/.cursor/mcp.json`
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`

## The 44 tools

**Tweets and threads**
`create_tweet`, `create_thread`, `list_tweets`, `get_tweet`, `update_tweet`, `delete_tweet`, `publish_tweet`, `schedule_tweet`, `batch_schedule` (up to 50 at once), `import_csv` (AI writes a post per row, scheduled from the row's date and time), `repurpose_tweet`

`create_tweet` and `create_thread` take an optional `platforms` array. Pass `["x", "bluesky", "linkedin"]` to publish the same content to all three networks in one call, or `["linkedin"]` to post to LinkedIn only. LinkedIn posts go to the connected personal profile, and a thread goes to LinkedIn as one post. An explicit list is always honoured exactly.

Leaving `platforms` out is not the same as pinning the post to X. An unspecified post follows the account's auto cross-post setting: when that is on, it goes to every connected network. Call `list_platforms` first if you need to know where an unspecified post will land. It separates what an unspecified post is attempted on from the subset that will actually land, and separates `connected` from `usable`, so a network whose authorisation expired shows as needing a reconnect instead of looking healthy. Either way the response carries a per-network result so you can see what published, failed, or was skipped.

**Media and AI generation**
`upload_media`, `generate_image`, `generate_video`

**Analytics and insights**
`get_analytics`, `get_top_posts`, `get_profile_growth`, `get_best_times`, `analyze_best_times`, `get_content_gaps`, `search_inspiration`

**Account and cross-posting**
`get_account`, `list_accounts` (multi-account: pass `x_account_id` to any tool), `list_platforms` (what an unspecified post targets, the auto cross-post setting, and which networks can publish right now)

**Evergreen queue**
`get_evergreen_settings`, `update_evergreen_settings`, `list_evergreen_posts`, `get_evergreen_post`, `add_to_evergreen`, `update_evergreen_post`, `remove_from_evergreen`, `get_evergreen_history`

**Articles (long-form X posts)**
`create_article`, `get_article`, `list_articles`, `update_article`, `delete_article`, `publish_article`

**DM campaigns** (Advanced and Agency plans)
`dm_campaign_create`, `dm_campaign_list`, `dm_campaign_report`, `dm_leads_list`, `dm_lead_approve`, `dm_inbox_list`

Plus MCP resources (account status, scheduled queue) and built-in prompts.

## Example prompts

- "Write 3 tweets about TypeScript tips and schedule them across this week at my best posting times."
- "Turn this blog post into a thread and schedule it for tomorrow 9am."
- "What were my top 5 tweets this month? Add the best one to my evergreen queue."
- "Check my posting streak and content gaps, then draft tweets to fill them."

## How it compares

X's official MCP server (XMCP) exposes the raw X API and can post, but it requires an X developer account, OAuth app credentials, and pay-per-use API billing, and it has no scheduling. OpenTweet is the managed publishing layer: flat pricing from $19.99/month, scheduling, threads, evergreen recycling, and analytics included. Full comparison: [opentweet.io/mcp/post-to-x](https://opentweet.io/mcp/post-to-x).

## Links

- Setup guide: [opentweet.io/twitter-mcp-server](https://opentweet.io/twitter-mcp-server)
- REST API docs: [opentweet.io/docs/api](https://opentweet.io/docs/api)
- Pricing: [opentweet.io/pricing](https://opentweet.io/pricing) (7-day free trial)
- npm: [@opentweet/mcp-server](https://www.npmjs.com/package/@opentweet/mcp-server)

## License

MIT