X/Twitter MCP Server

A Model Context Protocol (MCP) server that provides unofficial X/Twitter API access through browser automation using Playwright. This server enables AI agents and applications to interact with X/Twitter programmatically for content creation, scraping, and social media automation.

🚀 Features

Content Creation & Interaction

Tweet & Thread Posting: Post single tweets or multi-tweet threads with media support
Post Interactions: Like, unlike, retweet, unretweet, bookmark, quote tweet, and reply to posts
Comment Management: Like, unlike, reply to, and edit comments
Media Support: Upload and attach images, videos, and GIFs to tweets

Content Scraping & Analysis

Timeline Scraping: Extract posts from "For You" and "Following" timelines
Profile Scraping: Get comprehensive user profile data and recent posts
Search Functionality: Advanced search with filters for viral content, specific users, and date ranges
Comment Scraping: Extract comments and replies from specific posts
Trending Topics: Retrieve current trending topics and hashtags

MCP Integration

Dual Transport Support: Works with both stdio and HTTP/SSE transports
Tool-based Interface: 20+ tools available for AI agents to interact with X/Twitter
Structured Responses: JSON-formatted responses with comprehensive metadata
Error Handling: Robust error handling with descriptive error messages

📋 Prerequisites

Node.js 18+
Valid X/Twitter account credentials
Docker (optional, for containerized deployment)

Quick Start

Add this configuration to your Claude Desktop config file:

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

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password"
      }
    }
  }
}

With proxy (optional):

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password",
        "PROXY_URL": "http://proxy-server:port"
      }
    }
  }
}

Restart Claude Desktop

That's it! Claude can now interact with X/Twitter through 25+ powerful tools including:

tweet: Post a new tweet with optional media
thread: Post a multi-tweet thread
search_twitter: Search for tweets with advanced filters
scrape_profile: Get comprehensive user profile data
scrape_timeline: Extract posts from timelines
like_post, retweet_post, bookmark_post: Interact with posts
And many more for comprehensive X/Twitter automation

Example Usage

Try asking Claude:

"Can you post a tweet saying 'Hello from Claude!'"
"Can you search for tweets about Claude AI?"
"Can you scrape Elon Musk's profile and show me his latest 5 tweets?"
"Can you post a thread about the benefits of AI?"

🛠️ Installation

Local Development Installation

Clone the repository:

git clone <repository-url>
cd x-mcp

Install dependencies:

npm install

Build the project:

npm run build

Docker Installation

Build the Docker image:

docker build -t x-mcp .

Or use Docker Compose:

docker-compose --profile mcp up --build

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Required: X/Twitter credentials
TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password

# Optional: Proxy configuration
PROXY_URL=http://proxy-server:port          # Full proxy URL (supports http/https)
# or with authentication
PROXY_URL=http://username:password@proxy-server:port
# or separately
PROXY_URL=http://proxy-server:port
PROXY_USERNAME=proxy_username               # Optional: separate username
PROXY_PASSWORD=proxy_password               # Optional: separate password

# Optional: MCP server configuration
MCP_TRANSPORT=stdio           # Options: stdio, sse, http
MCP_PORT=3000                # Port for HTTP/SSE transport

# Optional: Directory for authentication state (default: playwright/.auth)
AUTH_DIR=playwright/.auth

Authentication Setup

(Optional) Create authentication directory or set AUTH_DIR environment variable:

export AUTH_DIR=/path/to/auth/dir
mkdir -p "${AUTH_DIR:-playwright/.auth}"

npm run cli login
# or
node dist/cli.js login

🔧 Available MCP Tools

The server provides 25+ tools for comprehensive X/Twitter interaction:

Authentication & Setup

login - Authenticate with X/Twitter

Content Creation

tweet - Post a single tweet with optional media
thread - Post a multi-tweet thread
reply_to_post - Reply to a specific post
quote_tweet - Quote tweet with additional text

Post Interactions

like_post / unlike_post - Like/unlike posts
retweet_post / unretweet_post - Retweet/unretweet posts
bookmark_post / unbookmark_post - Bookmark management

Comment Interactions

like_comment_by_id / unlike_comment_by_id - Like/unlike comments
reply_to_comment_by_id - Reply to comments
replace_comment_by_id - Edit comments (if supported)

Content Scraping

scrape_posts - Scrape posts from current page
scrape_profile - Get user profile and recent posts
scrape_comments - Extract comments from posts
scrape_timeline - Scrape For You/Following timelines
scrape_trending - Get trending topics
search_twitter - General search functionality
search_viral - Search for viral content with minimum engagement

📊 Data Structures

TwitterPost

interface TwitterPost {
  postId: string;
  author: TwitterUser;
  content: string;
  timestamp: Date;
  media: TwitterMedia[];
  metrics: PostMetrics;
  engagementRate: number;
  isRetweet?: boolean;
  retweetedFrom?: TwitterUser;
  quotedPost?: TwitterPost;
  url: string;
}

TwitterProfile

interface TwitterProfile extends TwitterUser {
  bannerUrl?: string;
  bio?: string;
  location?: string;
  website?: string;
  joinedDate?: Date;
  followingCount: number;
  followersCount: number;
  postsCount: number;
  isFollowing?: boolean;
  isFollowedBy?: boolean;
  latestPosts?: TwitterPost[];
}

PostMetrics

interface PostMetrics {
  likesCount: number;
  retweetsCount: number;
  quotesCount: number;
  repliesCount: number;
  impressionsCount: number;
  bookmarksCount: number;
}

🔒 Security & Best Practices

Rate Limiting

Implement delays between requests to avoid rate limiting
Use reasonable limits for scraping operations
Monitor for rate limit responses

Authentication

Store credentials securely in environment variables
Session data is stored in the directory specified by the AUTH_DIR environment variable (default playwright/.auth/)
Regular re-authentication may be required

Error Handling

All operations include comprehensive error handling
Descriptive error messages for troubleshooting
Graceful degradation for missing elements

Proxy Configuration

Supports HTTP/HTTPS proxies for all browser connections
Configure via PROXY_URL environment variable
Supports authentication with username/password
Useful for:
- Rotating IP addresses to avoid rate limits
- Accessing X/Twitter from restricted networks
- Adding an extra layer of anonymity
Example formats:
- Basic: http://proxy-server:port
- With auth: http://username:password@proxy-server:port
- Separate auth: Use PROXY_USERNAME and PROXY_PASSWORD

🐳 Docker Deployment

Using Docker Compose

# Start the MCP server
docker-compose --profile mcp up

# With environment variables
TWITTER_USERNAME=your_username TWITTER_PASSWORD=your_password docker-compose --profile mcp up

Custom Docker Run

docker run -d \
  --name x-mcp \
  -e TWITTER_USERNAME=your_username \
  -e TWITTER_PASSWORD=your_password \
  -e PROXY_URL=http://proxy-server:port \
  -e MCP_TRANSPORT=sse \
  -e MCP_PORT=3000 \
  -p 3000:3000 \
  x-mcp

🛠️ Development

Project Structure

src/
├── mcp.ts                    # Main MCP server implementation
├── cli.ts                    # Command line interface
├── types.ts                  # TypeScript type definitions
├── utils.ts                  # Utility functions
├── behaviors/                # User interaction behaviors
│   ├── login.ts             # Authentication logic
│   ├── interact-with-post.ts # Post interaction functions
│   ├── interact-with-comment.ts # Comment interaction functions
│   └── upload-media.ts      # Media upload functionality
└── scrapers/                # Data scraping modules
    ├── index.ts             # Scraper exports
    ├── post-scraper.ts      # Post scraping logic
    ├── profile-scraper.ts   # Profile scraping logic
    ├── comment-scraper.ts   # Comment scraping logic
    ├── search-scraper.ts    # Search functionality
    ├── timeline-scraper.ts  # Timeline scraping
    └── utils.ts             # Scraping utilities

Building and Testing

# Build TypeScript
npm run build

# Run MCP server
npm run mcp

# Run CLI commands
npm run cli <command>

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Guidelines

Follow TypeScript best practices
Add comprehensive error handling
Update type definitions for new features
Test with real X/Twitter interactions
Document new functionality

⚠️ Disclaimers

This is an unofficial tool using browser automation
X/Twitter's terms of service apply
Use responsibly and respect rate limits
UI changes may require updates to selectors
Not affiliated with X/Twitter

📄 License

[License information here]

🐛 Troubleshooting

Common Issues

Authentication Failures

Verify credentials in .env file
Try logging in again with npm run cli login
Check for 2FA requirements

Element Not Found Errors

X/Twitter may have updated their UI
Clear browser cache and re-authenticate
Check for element selector updates

Rate Limiting

Reduce request frequency
Add delays between operations
Use smaller batch sizes

Container Issues

Ensure proper environment variables
Check port availability
Verify Docker network configuration

For more help, please open an issue on the project repository.