What is X Mcp

x-mcp is an MCP Server designed to provide unofficial access to X/Twitter’s functionalities through browser automation using Playwright. It allows AI agents and applications to interact programmatically with X/Twitter for various tasks.

Use cases

Use cases for x-mcp include automating social media posts, scraping data for analysis, managing user interactions on X/Twitter, and monitoring trending topics.

How to use

To use x-mcp, configure your Claude Desktop config file with your Twitter credentials and the necessary command to run the server. Ensure you have Node.js 18+ and optionally Docker for deployment.

Key features

Key features include tweet and thread posting, post interactions (like, retweet, etc.), content scraping from timelines and profiles, advanced search capabilities, and robust error handling. It also supports dual transport methods and provides structured JSON responses.

Where to use

x-mcp can be used in various fields such as social media management, content creation, data analysis, and automation for marketing strategies.

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

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

Docker Installation

1. Build the Docker image:

docker build -t x-mcp .

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

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