Twitter MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to post tweets to Twitter/X with support for text and images, plus AI-powered image generation.

Features

• Post text tweets via OAuth 2.0
• Upload and attach images (up to 4 per tweet) via OAuth 1.0a
• NEW: AI image generation using Google Gemini
• Automatic token refresh for OAuth 2.0
• Secure credential storage in ~/.twitter_cli/
• Configurable image storage directory
• Easy setup with interactive CLI tools

Prerequisites

1. Node.js 18+ - Download
2. Twitter Developer Account - Sign up
3. Twitter App with the following:
   • OAuth 2.0 enabled with PKCE
   • OAuth 1.0a enabled (for media uploads)
   • Read and write permissions
   • Callback URL: http://localhost:8085/callback
4. Google Gemini API Key (Optional - for image generation) - Get API Key

Getting Your Twitter API Credentials

Step 1: Create a Twitter Developer Account

1. Go to Twitter Developer Portal
2. Sign in with your Twitter account
3. Apply for a developer account (if you haven't already)
4. Create a new project and app

Step 2: Configure Your App

1. Go to your app's settings in the Developer Portal
2. Navigate to "User authentication settings"
3. Click "Set up"
4. Configure the following:
   • App permissions: Select "Read and write"
   • Type of App: Select "Web App, Automated App or Bot"
   • Callback URI / Redirect URL: Enter http://localhost:8085/callback
   • Website URL: Enter any valid URL (e.g., https://example.com)

Step 3: Get OAuth 2.0 Credentials

1. In your app settings, go to "Keys and tokens" tab
2. Under "OAuth 2.0 Client ID and Client Secret", you'll find:
   • Client ID (starts with a random string)
   • Client Secret (click "Regenerate" if needed)
3. Save these for the OAuth 2.0 setup

Step 4: Get OAuth 1.0a Credentials

1. In the same "Keys and tokens" tab
2. Under "Authentication Tokens", you'll find:
   • API Key (also called Consumer Key)
   • API Key Secret (also called Consumer Secret)
   • Access Token
   • Access Token Secret
3. If you don't see Access Token/Secret, click "Generate"
4. Save these for the OAuth 1.0a setup

Installation

# Clone or download this package
cd twitter-package

# Install dependencies
npm install

Setup

1. Set Up OAuth 2.0 (Required for posting tweets)

Run the OAuth 2.0 setup wizard:

npm run setup-oauth2

You'll be prompted to:

1. Enter your Client ID
2. Enter your Client Secret
3. Authorize the app in your browser
4. Complete the authentication flow

This will save your credentials to ~/.twitter_cli/config.json and ~/.twitter_cli/tokens.json.

2. Set Up OAuth 1.0a (Required for image uploads)

Run the OAuth 1.0a setup wizard:

npm run setup-oauth1

You'll be prompted to:

1. Enter your API Key (Consumer Key)
2. Enter your API Key Secret (Consumer Secret)
3. Enter your Access Token
4. Enter your Access Token Secret

This will save your credentials to ~/.twitter_cli/oauth1_tokens.json.

3. Set Up Google Gemini API (Optional - for image generation)

Run the Gemini API setup wizard:

npm run setup-gemini

You'll be prompted to:

1. Enter your Gemini API Key (get it from https://aistudio.google.com/apikey)
2. Configure image storage directory (default: ~/.twitter_cli/generated_images)

This will save your configuration to ~/.twitter_cli/gemini.json.

4. Quick Setup (All Services)

To run all setup wizards in sequence:

# Twitter only
npm run setup

# Twitter + Gemini (includes everything)
npm run setup:all

Usage

Running the MCP Servers

Start the Twitter MCP server:

npm start

Start the Image Generation MCP server:

npm run start:image

The servers will run on stdio and can be used with Claude Desktop or other MCP clients.

Configuring Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["/absolute/path/to/twitter-package/src/mcp-server/index.js"]
    },
    "generate-image": {
      "command": "node",
      "args": ["/absolute/path/to/twitter-package/src/mcp-server/generate-image.js"]
    }
  }
}

Replace /absolute/path/to/twitter-package/ with the actual path to this directory.

Note: Both servers can run simultaneously in Claude Desktop!

Using with Claude

Once configured, you can ask Claude to:

Post tweets:

Post a tweet saying "Hello from Claude! 👋"

Post tweets with images:

Post a tweet "Check out this amazing view!" with /path/to/image.jpg

Generate AI images:

Generate an image of a futuristic cityscape at sunset

Generate and tweet an image:

Generate an image of a cute robot, then post it to Twitter with the caption "Meet my new AI friend! 🤖"

MCP Tool Reference

post_tweet

Post a tweet to Twitter/X with optional images.

Parameters:

• text (string, required): The tweet text (max 280 characters)
• image_paths (array of strings, optional): Paths to image files (max 4 images)

Returns:

• Success message with tweet URL and ID

Example:

{
  "text": "Hello from the MCP server!",
  "image_paths": ["/path/to/image1.jpg", "/path/to/image2.png"]
}

generate_image

Generate an AI image using Google's Gemini API based on a text prompt.

Parameters:

• prompt (string, required): Text description of the image to generate

Returns:

• Generated image path and accompanying text

Example:

{
  "prompt": "A serene mountain landscape at sunset with a lake reflection"
}

Configuration:

The image storage directory can be configured in three ways (priority order):

1. Environment variable: export TWITTER_MCP_IMAGE_DIR="/your/custom/path"
2. Config file: Add "image_storage_dir": "/your/custom/path" to ~/.twitter_cli/gemini.json
3. Default: ~/.twitter_cli/generated_images

File Structure

twitter-package/
├── package.json                 # Package configuration
├── README.md                    # This file
├── SETUP_GUIDE.md              # Quick setup guide
├── src/
│   ├── mcp-server/
│   │   ├── index.js            # Twitter MCP server
│   │   └── generate-image.js  # Image generation MCP server
│   ├── auth/
│   │   ├── oauth2-setup.js     # OAuth 2.0 setup wizard
│   │   ├── oauth1-setup.js     # OAuth 1.0a setup wizard
│   │   └── gemini-setup.js     # Gemini API setup wizard
│   └── lib/
│       └── config.js           # Shared configuration utilities
└── ~/.twitter_cli/              # Created during setup
    ├── config.json             # OAuth 2.0 client credentials
    ├── tokens.json             # OAuth 2.0 access/refresh tokens
    ├── oauth1_tokens.json      # OAuth 1.0a credentials
    ├── gemini.json             # Gemini API configuration
    └── generated_images/       # Generated images storage (default)

Configuration Files

All configuration files are stored in ~/.twitter_cli/ with secure permissions (0600).

config.json (OAuth 2.0 Client Credentials)

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

tokens.json (OAuth 2.0 Access Tokens)

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_at": 1234567890,
  "scope": "tweet.read tweet.write users.read offline.access"
}

oauth1_tokens.json (OAuth 1.0a Credentials)

{
  "oauth1_api_key": "your_api_key",
  "oauth1_api_secret": "your_api_secret",
  "access_token": "your_access_token",
  "access_token_secret": "your_access_token_secret"
}

gemini.json (Gemini API Configuration)

{
  "gemini_api_key": "your_gemini_api_key",
  "image_storage_dir": "/custom/path/to/images"
}

Troubleshooting

Authentication Errors

Error: "Not authenticated. Run 'npm run setup-oauth2' first."

• You need to run the OAuth 2.0 setup: npm run setup-oauth2

Error: "OAuth 1.0a credentials not found. Run 'npm run setup-oauth1' first."

• You need to run the OAuth 1.0a setup: npm run setup-oauth1

Error: "Failed to refresh token"

• Your refresh token may have expired
• Re-run the OAuth 2.0 setup: npm run setup-oauth2

Media Upload Errors

Error: "Failed to upload media"

• Ensure you've run OAuth 1.0a setup: npm run setup-oauth1
• Verify your app has "Read and write" permissions in Twitter Developer Portal
• Check that your image file exists and is a supported format (jpg, png, gif, webp)
• Ensure image is under 15MB

Permission Errors

Error: "403 Forbidden"

• Your app may not have the correct permissions
• Go to Twitter Developer Portal → Your App → Settings
• Ensure "Read and write" permissions are enabled
• You may need to regenerate your tokens after changing permissions

Image Generation Errors

Error: "Gemini API key not found. Run 'npm run setup-gemini' first."

• You need to set up Gemini API: npm run setup-gemini

Error: "Failed to generate image"

• Verify your Gemini API key is valid
• Check your API quota at https://aistudio.google.com/
• Ensure your prompt is appropriate and follows content policies
• Try a simpler or more specific prompt

Error: "Image storage directory permission denied"

• Check that the configured storage directory is writable
• Default location: ~/.twitter_cli/generated_images
• Change directory in ~/.twitter_cli/gemini.json if needed

Security

• All credentials are stored in ~/.twitter_cli/ with secure file permissions (0600)
• OAuth 2.0 uses PKCE (Proof Key for Code Exchange) for enhanced security
• Access tokens are automatically refreshed when expired
• Never commit your ~/.twitter_cli/ directory to version control

API Limits

• Tweet length: 280 characters
• Images per tweet: 4 maximum
• Image size: 15MB per image
• Supported formats: JPG, PNG, GIF, WebP
• Rate limits: Standard Twitter API rate limits apply

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues and questions:

• Check the Twitter API Documentation
• Review MCP Documentation
• Open an issue on GitHub

Credits

Built with:

• Model Context Protocol SDK
• axios
• oauth-1.0a