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

1. 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"
      }
    }
  }
}

1. 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

1. Clone the repository:

git clone <repository-url>
cd x-mcp

1. Install dependencies:

npm install

1. Build the project:

npm run build

Docker Installation

1. Build the Docker image:

docker build -t x-mcp .

1. 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

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

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

1. Login to X/Twitter (stores session for reuse):

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. 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.