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

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

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "your_api_key",
        "API_SECRET_KEY": "your_api_secret_key",
        "ACCESS_TOKEN": "your_access_token",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

Configuration

Step 1: Get Twitter API Credentials

Visit Twitter Developer Portal
Create a new App or use an existing one
Navigate to "Keys and Tokens"
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:

%APPDATA%\Claude\claude_desktop_config.json

Or navigate to:

C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

macOS

Edit the configuration file located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

Edit the configuration file located at:

~/.config/Claude/claude_desktop_config.json

Step 3: Add MCP Server Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "your_api_key",
        "API_SECRET_KEY": "your_api_secret_key",
        "ACCESS_TOKEN": "your_access_token",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

For security, consider using environment variables in production:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "${TWITTER_API_KEY}",
        "API_SECRET_KEY": "${TWITTER_API_SECRET_KEY}",
        "ACCESS_TOKEN": "${TWITTER_ACCESS_TOKEN}",
        "ACCESS_TOKEN_SECRET": "${TWITTER_ACCESS_TOKEN_SECRET}"
      }
    }
  }
}

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

Open Claude Desktop Settings
- Click on your profile icon or the settings gear in Claude Desktop
- Navigate to Settings
Go to Connectors
- In the Settings menu, find and click on Connectors
Enable Filesystem Access
- Click on Browse Connectors
- Select Desktop Extensions
- Find and click on Filesystem
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
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:

Ask Claude: "List files in the directory I gave you access to"
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:

Post a tweet: "Hello World! 🌍"

Posting with Images

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

Tweet with Image:

Post this image with caption: "Check out this amazing view!"
take image from desktop

Working with Images:

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

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)

Supported Image Formats:

JPEG/JPG (image/jpeg)
PNG (image/png)
GIF (image/gif)
WEBP (image/webp)

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

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:

Search for tweets about "artificial intelligence"

Advanced Search:

Search for 50 tweets about "climate change" from the past week

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:

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;
  };
}

Example:

// Request:
{
  "query": "machine learning",
  "count": 25
}

// Response:
{
  "status": "success",
  "message": "Search completed successfully",
  "data": {
    "tweets": [
      {
        "id": "1234567891",
        "text": "Exploring machine learning concepts...",
        "author_id": "user123",
        "created_at": "2025-11-06T12:00:00.000Z"
      }
      // ... more tweets
    ],
    "meta": {
      "result_count": 25,
      "next_token": "abc123xyz"
    }
  }
}

Development

Local Development Setup

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Set up environment:

Create a .env file in the project root:

API_KEY=your_api_key
API_SECRET_KEY=your_api_secret
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

Run locally:

Update your Claude config to use local build:

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["${absolute_path_to_project}/build/index.js"],
      "envFile": ".env"
    }
  }
}

Development commands:

# Start the server
npm start

# Run tests
npm test

# Build for production
npm run build

# Publish to npm (maintainers only)
npm publish --access public

Project Structure

twitter-mcp/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── twitter-api.ts     # Twitter API client
│   ├── types.ts           # TypeScript type definitions
│   ├── formatter.ts       # Response formatting
│   ├── types/            # Type declarations
│   │   └── modelcontextprotocol.d.ts
│   └── evals/
│       └── evals.ts       # Test utilities
├── .github/              # GitHub Actions workflows
│   └── workflows/
│       └── ci.yml        # CI pipeline
├── build/               # Compiled JavaScript (generated)
├── package.json        # Project metadata and dependencies
├── tsconfig.json       # TypeScript configuration
├── .gitignore         # Git ignore rules
├── .env.example       # Example environment variables
├── CHANGELOG.md       # Version history
├── CONTRIBUTING.md    # Contribution guidelines
└── README.md         # Project documentation

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:

# Remove old dependencies
rm -rf node_modules package-lock.json

# Reinstall
npm install

# Rebuild
npm run build

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:

%APPDATA%\Claude\logs\

macOS:

~/Library/Logs/Claude/

Linux:

~/.config/Claude/logs/

Environment Variables

The server requires the following environment variables:

Variable	Description	Required
`API_KEY`	Twitter API Key	Yes
`API_SECRET_KEY`	Twitter API Secret Key	Yes
`ACCESS_TOKEN`	Twitter Access Token	Yes
`ACCESS_TOKEN_SECRET`	Twitter Access Token Secret	Yes

Security Best Practices

Never commit credentials to version control
Use environment variables for sensitive data
Rotate credentials periodically
Monitor API usage in Twitter Developer Portal
Set up alerts for unusual activity
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:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Writing Tests

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

Contributing

Contributions are welcome! Please follow these steps:

Fork & Clone:

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

Create Branch:

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

Make Changes:
- Follow TypeScript practices
- Add/update tests
- Update documentation
Test & Build:
```
npm install
npm test
npm run build
```

Commit & Push:

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

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 genaiwithms

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

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

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "your_api_key",
        "API_SECRET_KEY": "your_api_secret_key",
        "ACCESS_TOKEN": "your_access_token",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

Configuration

Step 1: Get Twitter API Credentials

Visit Twitter Developer Portal
Create a new App or use an existing one
Navigate to "Keys and Tokens"
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:

%APPDATA%\Claude\claude_desktop_config.json

Or navigate to:

C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

macOS

Edit the configuration file located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

Edit the configuration file located at:

~/.config/Claude/claude_desktop_config.json

Step 3: Add MCP Server Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "your_api_key",
        "API_SECRET_KEY": "your_api_secret_key",
        "ACCESS_TOKEN": "your_access_token",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

For security, consider using environment variables in production:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@muhammadsiddiq/twitter-mcp"],
      "env": {
        "API_KEY": "${TWITTER_API_KEY}",
        "API_SECRET_KEY": "${TWITTER_API_SECRET_KEY}",
        "ACCESS_TOKEN": "${TWITTER_ACCESS_TOKEN}",
        "ACCESS_TOKEN_SECRET": "${TWITTER_ACCESS_TOKEN_SECRET}"
      }
    }
  }
}

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

Open Claude Desktop Settings
- Click on your profile icon or the settings gear in Claude Desktop
- Navigate to Settings
Go to Connectors
- In the Settings menu, find and click on Connectors
Enable Filesystem Access
- Click on Browse Connectors
- Select Desktop Extensions
- Find and click on Filesystem
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
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:

Ask Claude: "List files in the directory I gave you access to"
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:

Post a tweet: "Hello World! 🌍"

Posting with Images

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

Tweet with Image:

Post this image with caption: "Check out this amazing view!"
take image from desktop

Working with Images:

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

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)

Supported Image Formats:

JPEG/JPG (image/jpeg)
PNG (image/png)
GIF (image/gif)
WEBP (image/webp)

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

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:

Search for tweets about "artificial intelligence"

Advanced Search:

Search for 50 tweets about "climate change" from the past week

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:

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;
  };
}

Example:

// Request:
{
  "query": "machine learning",
  "count": 25
}

// Response:
{
  "status": "success",
  "message": "Search completed successfully",
  "data": {
    "tweets": [
      {
        "id": "1234567891",
        "text": "Exploring machine learning concepts...",
        "author_id": "user123",
        "created_at": "2025-11-06T12:00:00.000Z"
      }
      // ... more tweets
    ],
    "meta": {
      "result_count": 25,
      "next_token": "abc123xyz"
    }
  }
}

Development

Local Development Setup

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Set up environment:

Create a .env file in the project root:

API_KEY=your_api_key
API_SECRET_KEY=your_api_secret
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

Run locally:

Update your Claude config to use local build:

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["${absolute_path_to_project}/build/index.js"],
      "envFile": ".env"
    }
  }
}

Development commands:

# Start the server
npm start

# Run tests
npm test

# Build for production
npm run build

# Publish to npm (maintainers only)
npm publish --access public

Project Structure

twitter-mcp/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── twitter-api.ts     # Twitter API client
│   ├── types.ts           # TypeScript type definitions
│   ├── formatter.ts       # Response formatting
│   ├── types/            # Type declarations
│   │   └── modelcontextprotocol.d.ts
│   └── evals/
│       └── evals.ts       # Test utilities
├── .github/              # GitHub Actions workflows
│   └── workflows/
│       └── ci.yml        # CI pipeline
├── build/               # Compiled JavaScript (generated)
├── package.json        # Project metadata and dependencies
├── tsconfig.json       # TypeScript configuration
├── .gitignore         # Git ignore rules
├── .env.example       # Example environment variables
├── CHANGELOG.md       # Version history
├── CONTRIBUTING.md    # Contribution guidelines
└── README.md         # Project documentation

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:

# Remove old dependencies
rm -rf node_modules package-lock.json

# Reinstall
npm install

# Rebuild
npm run build

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:

%APPDATA%\Claude\logs\

macOS:

~/Library/Logs/Claude/

Linux:

~/.config/Claude/logs/

Environment Variables

The server requires the following environment variables:

Variable	Description	Required
`API_KEY`	Twitter API Key	Yes
`API_SECRET_KEY`	Twitter API Secret Key	Yes
`ACCESS_TOKEN`	Twitter Access Token	Yes
`ACCESS_TOKEN_SECRET`	Twitter Access Token Secret	Yes

Security Best Practices

Never commit credentials to version control
Use environment variables for sensitive data
Rotate credentials periodically
Monitor API usage in Twitter Developer Portal
Set up alerts for unusual activity
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:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Writing Tests

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

Contributing

Contributions are welcome! Please follow these steps:

Fork & Clone:

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

Create Branch:

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

Make Changes:
- Follow TypeScript practices
- Add/update tests
- Update documentation
Test & Build:
```
npm install
npm test
npm run build
```

Commit & Push:

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

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 genaiwithms

Twitter MCP Server

Twitter MCP Server

Features

Table of Contents

Development

Installation

Prerequisites

Quick Start

Configuration

Step 1: Get Twitter API Credentials

Step 2: Configure Claude Desktop

Windows

macOS

Linux

Step 3: Add MCP Server Configuration

Step 4: Restart Claude Desktop

Setting Up Filesystem Access in Claude Desktop

Step-by-Step Instructions

Verification

Common Paths to Consider

Troubleshooting

Usage

Posting Tweets

Posting with Images

Searching Tweets

API Reference

Tools

1. post_tweet

2. post_tweet_with_image

3. search_tweets

Development

Local Development Setup

Project Structure

Scripts

Troubleshooting

Common Issues

1. Authentication Errors

2. Rate Limits

3. Image Upload Issues

3. "Image Upload Failed"

4. "Module Not Found" Error

5. Server Not Responding in Claude

Debug Mode

Environment Variables

Security Best Practices

Limitations

Testing

Writing Tests

Contributing

Commit Messages

License

Support

Acknowledgments

Twitter MCP Server

Features

Table of Contents

Development

Installation

Prerequisites

Quick Start

Configuration

Step 1: Get Twitter API Credentials

Step 2: Configure Claude Desktop

Windows

macOS

Linux

Step 3: Add MCP Server Configuration

Step 4: Restart Claude Desktop

Setting Up Filesystem Access in Claude Desktop

Step-by-Step Instructions

Verification

Common Paths to Consider

Troubleshooting

Usage

Posting Tweets

Posting with Images

Searching Tweets

API Reference

Tools

1. post_tweet

1. `post_tweet`

2. `post_tweet_with_image`

3. `search_tweets`

1. `post_tweet`

2. `post_tweet_with_image`

3. `search_tweets`