Twitter MCP Server

A Model Context Protocol (MCP) server that enables seamless interaction with Twitter/X platform. Post tweets, share images, and search Twitter directly through Claude AI.

Features

• 🐦 Post Tweets - Share your thoughts with the world

• 🖼️ Image Support - Post tweets with images (JPG, PNG, GIF, WEBP)

• 🔍 Search Tweets - Find and analyze tweets by query

• 💬 Reply to Tweets - Engage in conversations

• 🔐 Secure Authentication - OAuth 1.0a authentication

• ⚡ Rate Limiting - Built-in protection against API limits

Table of Contents

• Installation

• Configuration

• Usage

  • Posting Tweets

  • Posting with Images

  • Searching Tweets

  Development

  Types:

  interface SearchTweetsRequest { query: string; // Search query string count: number; // Number of results (10-100) } interface SearchResponse { tweets: Tweet[]; meta: { result_count: number; next_token?: string; }; }

• Development

• Troubleshooting

• License

Installation

Prerequisites

• Node.js 18 or higher

• npm or npx

• Twitter Developer Account with API credentials

• Claude Desktop App

Quick Start

The easiest way to use this MCP server is through npx (no installation required):

Configuration

Step 1: Get Twitter API Credentials

1. Visit Twitter Developer Portal

2. Create a new App or use an existing one

3. Navigate to "Keys and Tokens"

4. Generate/Copy the following:

   • API Key

   • API Secret Key

   • Access Token

   • Access Token Secret

Step 2: Configure Claude Desktop

Windows

Edit the configuration file located at:

Or navigate to:

macOS

Edit the configuration file located at:

Linux

Edit the configuration file located at:

Step 3: Add MCP Server Configuration

Add the following to your claude_desktop_config.json:

For security, consider using environment variables in production:

Important: Replace the placeholder values with your actual Twitter API credentials.

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop completely for the changes to take effect.

Setting Up Filesystem Access in Claude Desktop

Claude Desktop needs permission to access files and folders on your computer. Follow these simple steps to grant access:

Step-by-Step Instructions

1. Open Claude Desktop Settings

   • Click on your profile icon or the settings gear in Claude Desktop

   • Navigate to Settings

2. Go to Connectors

   • In the Settings menu, find and click on Connectors

3. Enable Filesystem Access

   • Click on Browse Connectors

   • Select Desktop Extensions

   • Find and click on Filesystem

4. Add Directory Path

   • Enter the full path to the directory you want Claude to access

   • Examples:

     • Windows: C:\Users\YourName\TwitterImages

     • macOS: /Users/yourname/TwitterImages

     • Linux: /home/yourname/TwitterImages

   💡 Tip: You can add multiple directories by repeating this step

5. Save and Restart

   • Click Save or Apply

   • Close Claude Desktop completely

   • Reopen Claude Desktop for changes to take effect

Verification

To verify filesystem access is working:

1. Ask Claude: "List files in the directory I gave you access to"

2. Or provide a specific path: "Show me files in C:\Users\YourName\TwitterImages"

If Claude can see your files, you're all set! 🎉

Common Paths to Consider

• For Twitter images: Create a dedicated folder like:

  • C:\TwitterImages (Windows)

  • ~/TwitterImages (macOS/Linux)

• For documents:

  • C:\Users\YourName\Documents (Windows)

  • ~/Documents (macOS/Linux)

Troubleshooting

Can't find Connectors in Settings?

• Make sure you're using the latest version of Claude Desktop

• Try restarting the application

Path not working?

• Use the full absolute path (complete path from root)

• Avoid spaces in folder names, or use quotes around the path

• Check that the directory actually exists on your computer

Changes not taking effect?

• Make sure you completely closed Claude Desktop (check system tray/menu bar)

• Wait a few seconds before reopening

• Restart your computer if issues persist

Usage

Once configured, you can interact with Twitter through natural language commands to Claude.

Posting Tweets

Simple Tweet:

Posting with Images

Important: Make sure you have configured the filesystem MCP server as shown in Step 4.

Tweet with Image:

Working with Images:

1. File Access:

• The filesystem MCP server must be configured to access local images

• Images must be in an accessible location on your computer

• Both absolute and relative paths are supported

2. Path Formats:

• Windows: C:\Users\YourName\Pictures\image.jpg

• macOS: /Users/YourName/Pictures/image.jpg

• Linux: /home/yourname/pictures/image.jpg

• Relative: ./images/photo.jpg (relative to your working directory)

3. Supported Image Formats:

• JPEG/JPG (image/jpeg)

• PNG (image/png)

• GIF (image/gif)

• WEBP (image/webp)

4. Image Requirements:

• Maximum file size: 5MB for static images, 15MB for GIFs

• Recommended dimensions: 1200x675 pixels (16:9 aspect ratio)

• File permissions: Must be readable by the Claude Desktop app

5. Best Practices:

• Use relative paths when possible for portability

• Keep images in a dedicated folder for better organization

• Consider image optimization for better upload performance

• Test with small images first

Searching Tweets

Basic Search:

Advanced Search:

API Reference

Tools

The server provides three tools that can be accessed through Claude:

1. post_tweet

Post a text-only tweet.

2. post_tweet_with_image

Post a tweet with an attached image.

Supported Image Formats:

• JPEG/JPG

• PNG

• GIF (animated, max 15MB)

• WEBP

3. search_tweets

Search for tweets matching a query.

Types:

Example:

Development

Local Development Setup

1. Clone the repository:

2. Install dependencies:

3. Build the project:

4. Set up environment:

Create a .env file in the project root:

5. Run locally:

Update your Claude config to use local build:

6. Development commands:

Project Structure

Scripts

• npm run build - Compile TypeScript to JavaScript

• npm start - Run the compiled server

• npm run prepublishOnly - Build before publishing

Troubleshooting

Common Issues

1. Authentication Errors

Problem: "401 Unauthorized" or authentication failed

Solutions:

• Verify Twitter API credentials in Developer Portal

• Ensure all four tokens are correct and complete

• Check app permissions (needs Read + Write)

• Try regenerating access tokens

• Verify .env file format if using local development

2. Rate Limits

Problem: "Rate limit exceeded" or requests failing

Solutions:

• Built-in rate limiting protects against overuse

• Wait 15 minutes for limits to reset

• Check your Twitter API tier limits

• Use exponential backoff for retries

• Monitor usage in Twitter Developer Portal

3. Image Upload Issues

Problem: Image upload fails or missing media

Solutions:

• Verify file exists and is readable

• Check size limits: 5MB (images), 15MB (GIFs)

• Ensure format is supported (JPG, PNG, GIF, WEBP)

• Use absolute file paths

• Check file permissions

• Verify image is not corrupted

3. "Image Upload Failed"

Problem: Image file cannot be uploaded.

Solutions:

• Verify the file path is correct and absolute

• Check file exists and is readable

• Ensure file size is under limits (5MB for images, 15MB for GIFs)

• Verify file format is supported (JPG, PNG, GIF, WEBP)

• Check file permissions

4. "Module Not Found" Error

Problem: Dependencies not installed or build not completed.

Solution:

5. Server Not Responding in Claude

Problem: MCP server not connecting to Claude.

Solutions:

• Restart Claude Desktop completely

• Check config file syntax is valid JSON

• Verify file path in config matches actual location

• Check Node.js is installed: node --version

• Look for errors in Claude's logs

Debug Mode

To see detailed logs, check:

Windows:

macOS:

Linux:

Environment Variables

The server requires the following environment variables:

Security Best Practices

1. Never commit credentials to version control

2. Use environment variables for sensitive data

3. Rotate credentials periodically

4. Monitor API usage in Twitter Developer Portal

5. Set up alerts for unusual activity

6. Use separate credentials for development and production

Limitations

• Maximum tweet length: 280 characters

• Image file size limits: 5MB (images), 15MB (GIFs)

• Rate limits apply based on your Twitter API tier

• Media must be uploaded before tweeting (handled automatically)

Testing

This project uses Jest for testing. Run tests with:

Writing Tests

Test files are located in src/evals/. Example test:

Contributing

Contributions are welcome! Please follow these steps:

1. Fork & Clone:

   git clone https://github.com/EnesCinr/twitter-mcp.git cd twitter-mcp

2. Create Branch:

   git checkout -b feature/your-feature # or git checkout -b fix/your-bugfix

3. Make Changes:

   • Follow TypeScript practices

   • Add/update tests

   • Update documentation

4. Test & Build:

   npm install npm test npm run build

5. Commit & Push:

   git add . git commit -m "feat: add amazing feature" git push origin feature/your-feature

6. Open Pull Request:

   • Use clear title and description

   • Reference issues if applicable

   • Include test results

   • Update documentation

Commit Messages

Follow Conventional Commits:

• feat: New feature

• fix: Bug fix

• docs: Documentation

• test: Tests

• refactor: Code refactoring

• chore: Maintenance

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues

• Documentation: MCP Documentation

• Twitter API: Twitter Developer Docs

Acknowledgments

• Built with Model Context Protocol SDK

• Uses twitter-api-v2 library

• Inspired by the Claude AI ecosystem

Made with ❤️ by