<!-- mcp-name: io.github.RyanKramer/shippost-mcp -->
# ShipPost MCP — Twitter/X tools for AI agents

Give any AI agent (Claude Code, Cursor, Windsurf, etc.) the ability to read, write, and engage on Twitter/X.

## Quick Start

### Claude Code

Add to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "twitter": {
      "command": "shippost-mcp",
      "env": {
        "TWITTER_ACCESS_TOKEN": "your-access-token",
        "TWITTER_REFRESH_TOKEN": "your-refresh-token",
        "TWITTER_CLIENT_ID": "your-client-id"
      }
    }
  }
}
```

### Install from PyPI

```bash
pip install shippost-mcp
```

## Free Tools

| Tool | Description |
|------|-------------|
| `get_my_profile` | Get your Twitter profile |
| `get_timeline` | Read your home timeline |
| `get_mentions` | Get tweets mentioning you |
| `get_user_profile` | Look up any user's profile |
| `get_tweet` | Get a specific tweet by ID |
| `search_tweets` | Search recent tweets |
| `post_tweet` | Post a tweet |
| `reply_to_tweet` | Reply to a tweet |
| `like_tweet` | Like a tweet |
| `retweet` | Retweet a tweet |
| `follow_user` | Follow a user |

## Paid AI Tools (requires ShipPost API key)

| Tool | Description |
|------|-------------|
| `find_opportunities` | AI scans your timeline for the best tweets to reply to |
| `draft_reply` | AI drafts a reply in your voice |
| `draft_tweet` | AI drafts an original tweet |
| `draft_thread` | AI drafts a full thread |
| `analyze_account` | AI analyzes any Twitter account |
| `get_performance` | AI-powered engagement analytics |

Get your API key at [shippost.ai](https://shippost.ai)

## Configuration

| Env Var | Required | Description |
|---------|----------|-------------|
| `TWITTER_ACCESS_TOKEN` | Yes | OAuth 2.0 access token |
| `TWITTER_REFRESH_TOKEN` | Recommended | For automatic token renewal |
| `TWITTER_CLIENT_ID` | For refresh | Your Twitter app's client ID |
| `SHIPPOST_API_KEY` | For AI features | Get at shippost.ai |

## License

MIT