🐦 X/Twitter MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop (and other MCP clients) to interact with X/Twitter — post tweets, read timelines, search content, manage follows, and monitor your account.

✨ Features

🔐 Flexible Authentication

• OAuth 1.0a — Full read + write access (post, reply, like, retweet, follow)
• Bearer Token — App-only read access (search, timelines, profiles)
• Per-call credentials — Pass credentials as tool arguments for multi-account setups
• Env var defaults — Set once in environment, reuse across all tool calls

🛡️ Security

• SSRF protection — Blocks private/internal IPs when uploading media from URLs
• Prompt injection protection — External content wrapped in randomised EXTCONTENT markers
• No secrets in code — All credentials resolved from env vars or per-call arguments

⚡ Performance

• In-memory client cache — Reuses authenticated clients (4h TTL) to avoid redundant handshakes
• Username → ID cache — Resolves @username to user IDs once, caches for 4h
• Token-bucket rate limiter — Respects X free-tier limits before hitting the API
• Auto-retry on 429 — Exponential backoff up to 3 retries on rate-limit responses

🧰 18 Tools (9 SENSE + 9 ACT)

SENSE — Read from X/Twitter: | Tool | Description | |------|-------------| | x_get_timeline | Home timeline — recent posts from followed accounts | | x_get_notifications | Mentions of the authenticated user | | x_search_tweets | Search by keyword, hashtag, or from:username | | x_get_tweet_thread | Fetch a tweet and its full conversation thread | | x_get_profile | User profile by username | | x_get_followers | Followers list for any account | | x_get_user_tweets | Recent tweets from a specific user | | x_search_users | Search for users by name or keyword | | x_get_media_specs | X/Twitter media format specs (dimensions, size limits, formats) |

ACT — Write to X/Twitter: | Tool | Description | |------|-------------| | x_create_tweet | Post a tweet (text, link card, image, or video) | | x_reply | Reply to a tweet | | x_create_thread | Post a series of connected tweets | | x_quote_tweet | Quote-tweet with commentary | | x_like | Like a tweet | | x_retweet | Retweet | | x_follow | Follow a user by username | | x_unfollow | Unfollow a user by username | | x_delete_tweet | Delete a tweet |

🚀 Quick Start

Prerequisites

• Node.js 22.14 or higher
• An X Developer account with an app created
• Claude Desktop (or any MCP-compatible client)

Get Your X API Credentials

1. Go to the X Developer Portal
2. Create a project and app
3. Under User authentication settings, set permissions to Read and write
4. Generate your keys:
   • Consumer Key → X_APP_KEY
   • Consumer Secret → X_APP_SECRET
   • Access Token → X_ACCESS_TOKEN
   • Access Token Secret → X_ACCESS_SECRET

For read-only access, a Bearer Token alone is sufficient.

📦 Installation

Published package: @luminarylane/x-twitter-mcp-server on npm

Option 0: Claude Code Plugin (Simplest for Claude Code Users) 🔌

If you're using Claude Code, install directly via the plugin system:

# Add the Luminary Lane Tools marketplace
/plugin marketplace add luminarylane/x-twitter-mcp-server

# Install the plugin
/plugin install x-twitter@luminary-lane-tools

Or install directly without adding the marketplace:

/plugin install x-twitter@luminarylane/x-twitter-mcp-server

Note: Set your X API credentials as environment variables before using the plugin.

Option 1: npx (Recommended — Zero Install) ⚡

Run directly without installation:

# Test it works
X_BEARER_TOKEN=your-token npx --yes @luminarylane/x-twitter-mcp-server

Claude Desktop configuration:

{
  "mcpServers": {
    "x-twitter": {
      "command": "npx",
      "args": ["--yes", "@luminarylane/x-twitter-mcp-server"],
      "env": {
        "X_APP_KEY": "your-consumer-key",
        "X_APP_SECRET": "your-consumer-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_SECRET": "your-access-token-secret"
      }
    }
  }
}

Read-only setup (bearer token only):

{ "env": { "X_BEARER_TOKEN": "your-bearer-token" } }

Option 2: Install from npm

npm install -g @luminarylane/x-twitter-mcp-server

Then configure Claude Desktop:

{
  "mcpServers": {
    "x-twitter": {
      "command": "luminarylane-x-twitter-mcp",
      "env": {
        "X_APP_KEY": "your-consumer-key",
        "X_APP_SECRET": "your-consumer-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_SECRET": "your-access-token-secret"
      }
    }
  }
}

Option 3: Install from Source

git clone https://github.com/luminarylane/x-twitter-mcp-server.git
cd x-twitter-mcp-server
npm install
npm run build

Then configure Claude Desktop:

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/x-twitter-mcp-server/dist/index.js"],
      "env": {
        "X_APP_KEY": "your-consumer-key",
        "X_APP_SECRET": "your-consumer-secret",
        "X_ACCESS_TOKEN": "your-access-token",
        "X_ACCESS_SECRET": "your-access-token-secret"
      }
    }
  }
}

🔑 Authentication

The server resolves credentials in this priority order:

| Priority | Mode | Env Vars | Access | | -------- | ------------ | ------------------------------------------------------------------- | ----------------- | | 1 | OAuth 1.0a | X_APP_KEY + X_APP_SECRET + X_ACCESS_TOKEN + X_ACCESS_SECRET | Full read + write | | 2 | Bearer Token | X_BEARER_TOKEN | Read-only | | 3 | Per-call | Pass as tool arguments | Either mode |

Per-call credentials let you manage multiple X accounts from one server instance — pass appKey, appSecret, accessToken, accessSecret (or bearerToken) directly as tool arguments.

💬 Usage Examples

Once configured, ask Claude to:

• "What's on my X timeline?"
• "Search for tweets about Model Context Protocol"
• "Post a tweet: Just shipped a new feature!"
• "Create a thread about the benefits of async programming"
• "Reply to tweet 1234567890 with 'Great point!'"
• "Like tweet 1234567890"
• "Follow @anthropic"
• "Get the profile for @sama"
• "Show me the full thread for tweet 1234567890"
• "What media formats does X support for video uploads?"

📊 Rate Limits

The server enforces X free-tier rate limits client-side before hitting the API:

| Category | Limit | Window | | --------------------------- | ------------ | -------- | | General reads | 450 requests | 15 min | | Timeline reads | 900 requests | 15 min | | Tweet creation | 50 tweets | 24 hours | | Likes | 1,000 likes | 24 hours | | Retweet / Follow / Unfollow | 5 actions | 15 min |

When a limit is reached the server returns a structured error with a retryAfterSeconds field and an action hint for the agent.

🔧 Troubleshooting

Credentials not working

Error: Missing credentials

Ensure all four OAuth 1.0a variables are set, or at minimum X_BEARER_TOKEN for read-only access.

401 Authentication failed

AUTH_FAILED: Credentials are invalid or expired.

Regenerate your Access Token and Secret in the X Developer Portal and update X_ACCESS_TOKEN / X_ACCESS_SECRET.

403 Permission denied

PERMISSION_DENIED: Your token may lack write permissions.

Go to X Developer Portal → App Settings → User authentication → Permissions and set it to Read and write, then regenerate your tokens.

403 Duplicate tweet

DUPLICATE_TWEET: X rejected this as a duplicate.

Change the tweet text to make it unique.

400 Tier restricted

TIER_RESTRICTED: This endpoint is not available on your X API tier.

Some endpoints (e.g., full-archive search) require a Basic or Pro tier. The x_search_tweets tool uses recent search which is available on the free tier.

Rate limit exceeded

Rate limited: Wait Xs then retry.

The server handles this automatically for short waits (≤ 60s). For longer windows it returns the retryAfterSeconds so the agent can defer the task.

Reporting Issues

1. Check existing issues
2. Open a new issue with:
   • Full error message
   • Steps to reproduce
   • Tool name used
   • Environment (OS, Node.js version)

📝 Open an Issue

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Type check
npx tsc --noEmit

# Run tests
npm test

# Format
npx prettier --write .

📝 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

• Anthropic for the MCP specification
• twitter-api-v2 for the excellent X API client