npm package: @opentweet/mcp-server
Description: OpenTweet MCP Server - Manage your Twitter/X presence from any AI assistant
Author: OpenTweet
Latest version: 1.1.3

# 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)

Schedule and manage your X (Twitter) posts directly from Claude Desktop, Claude Code, Cursor, and Windsurf. 18 tools for creating tweets, building threads, checking analytics, and managing your evergreen queue.

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

## Install

### Option 1: Claude Desktop Extension (One-Click)

Download the `.mcpb` extension from **[opentweet.io/claude-desktop](https://opentweet.io/claude-desktop)** and double-click it. Claude Desktop handles the rest — your API key is stored securely in your OS keychain.

### Option 2: Manual MCP Config

Works with Claude Desktop, Claude Code, Cursor, and Windsurf.

**Interactive installer** (auto-detects your MCP client):

```bash
npx -y @opentweet/mcp-server install
```

**Or add manually** to your MCP client config:

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

**For Claude Code:**
```bash
claude mcp add opentweet -- npx -y @opentweet/mcp-server
```

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

## Get Your API Key

1. Create an account at [opentweet.io](https://opentweet.io) (7-day free trial)
2. Connect your X/Twitter account
3. Go to the [Developer Dashboard](https://opentweet.io/developer) and create an API key

Your key starts with `ot_`.

## Tools

### Content Creation

| Tool | Type | Description |
|------|------|-------------|
| `opentweet_create_tweet` | Write | Create a tweet — save as draft, schedule for a specific time, or publish immediately |
| `opentweet_create_thread` | Write | Create a multi-tweet thread (2–25 tweets) |
| `opentweet_update_tweet` | Write | Edit tweet text, category, schedule, or media |
| `opentweet_delete_tweet` | Write | Permanently delete a tweet |
| `opentweet_upload_media` | Write | Upload images (JPG, PNG, GIF, WebP) or videos (MP4, MOV) to attach to tweets |

### Scheduling & Publishing

| Tool | Type | Description |
|------|------|-------------|
| `opentweet_publish_tweet` | Write | Publish a draft or scheduled tweet immediately to X |
| `opentweet_batch_schedule` | Write | Schedule up to 50 tweets at once with individual times |

### Reading & Analytics

| Tool | Type | Description |
|------|------|-------------|
| `opentweet_list_tweets` | Read | List tweets filtered by status (draft, scheduled, posted, failed) with pagination |
| `opentweet_get_tweet` | Read | Get full details of a specific tweet by ID |
| `opentweet_get_analytics` | Read | Get posting stats, streaks, trends, best times, and engagement data |
| `opentweet_get_account` | Read | Get account status, subscription plan, and daily posting limits |

### Evergreen Queue

| Tool | Type | Description |
|------|------|-------------|
| `opentweet_get_evergreen_settings` | Read | Get evergreen queue configuration and pool stats |
| `opentweet_update_evergreen_settings` | Write | Update evergreen posting schedule and settings |
| `opentweet_list_evergreen_posts` | Read | List all posts in the evergreen pool |
| `opentweet_add_to_evergreen` | Write | Add a post to the auto-recycling evergreen pool |
| `opentweet_update_evergreen_post` | Write | Update cooldown period or pause/resume an evergreen post |
| `opentweet_remove_from_evergreen` | Write | Remove a post from the evergreen pool |
| `opentweet_get_evergreen_history` | Read | View evergreen publishing history |

## Resources

| URI | Description |
|-----|-------------|
| `opentweet://account` | Account status and limits |
| `opentweet://posts/scheduled` | Currently scheduled tweets |
| `opentweet://posts/drafts` | Draft tweets |
| `opentweet://analytics/summary` | Analytics overview |

## Prompts

Four built-in prompt templates accessible from Claude's prompt menu:

| Prompt | Description |
|--------|-------------|
| **Weekly Content Plan** | Generate 7–14 tweet drafts across a week, scheduled at optimal times |
| **Review & Schedule Drafts** | Pull all drafts, suggest improvements, find best posting times, batch schedule |
| **Content from URL** | Generate 3–5 tweet variations from a URL, article, or topic |
| **Performance Review** | Analyze posting analytics, identify trends, get improvement suggestions |

## Examples

### Check your analytics

> "What's my posting streak and when should I post for the most engagement?"

Claude uses `opentweet_get_analytics` to fetch your stats and best posting times.

### Schedule a tweet

> "Schedule a tweet about the importance of writing documentation for tomorrow at 9am"

Claude creates the tweet and schedules it using `opentweet_create_tweet`.

### Create a thread

> "Create a 5-tweet thread about TypeScript migration tips, save as draft"

Claude builds a complete thread using `opentweet_create_thread` — hook, tips, and closer.

### Plan a week of content

> "Plan my tweets for next week about AI and startups, 2 per day, casual tone"

Claude uses the **Weekly Content Plan** prompt to generate and schedule 14 drafts.

### Manage evergreen content

> "Add my top 3 performing tweets to the evergreen queue with a 14-day cooldown"

Claude lists your posts, picks the best ones, and adds them to auto-recycling with `opentweet_add_to_evergreen`.

## Security

- **Desktop Extension:** API key stored in OS keychain (macOS Keychain / Windows Credential Manager), never in plaintext
- **Write operations** (creating, publishing, deleting) require explicit user confirmation in Claude Desktop
- **Read operations** (analytics, listing tweets) run automatically
- All communication uses HTTPS to the OpenTweet API

## Privacy

OpenTweet's privacy policy: [opentweet.io/privacy](https://opentweet.io/privacy)

The MCP server sends your tweets and requests to the OpenTweet API. No data is stored locally beyond the API key. Your X/Twitter credentials are managed by OpenTweet's servers — the MCP server never has direct access to them.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENTWEET_API_KEY` | Yes | Your OpenTweet API key (starts with `ot_`) |
| `OPENTWEET_BASE_URL` | No | API base URL (default: `https://opentweet.io`) |

## Development

```bash
git clone https://github.com/opentweetio/mcp-server.git
cd mcp-server
npm install
npm run build
```

To build the Claude Desktop Extension (`.mcpb`):

```bash
npm run build:mcpb
```

## Links

- [OpenTweet](https://opentweet.io)
- [Claude Desktop Extension](https://opentweet.io/claude-desktop)
- [MCP Setup Guide](https://opentweet.io/mcp)
- [Developer Dashboard](https://opentweet.io/developer)

## License

[MIT](LICENSE)