# X Mcp > An MCP Server to interact with X/Twitter besides the official API. - **Type:** MCP server - **Install:** `agentstack add mcp-barresider-x-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Barresider](https://agentstack.voostack.com/s/barresider) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Barresider](https://github.com/Barresider) - **Source:** https://github.com/Barresider/x-mcp ## Install ```sh agentstack add mcp-barresider-x-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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` ```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): ```json { "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: ```bash git clone cd x-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ### Docker Installation 1. Build the Docker image: ```bash docker build -t x-mcp . ``` 2. Or use Docker Compose: ```bash docker-compose --profile mcp up --build ``` ## ⚙️ Configuration ### Environment Variables Create a `.env` file in the project root: ```env # 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: ```bash export AUTH_DIR=/path/to/auth/dir mkdir -p "${AUTH_DIR:-playwright/.auth}" ``` 2. Login to X/Twitter (stores session for reuse): ```bash 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 ```typescript 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 ```typescript 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 ```typescript 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 ```bash # 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 ```bash 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 ```bash # Build TypeScript npm run build # Run MCP server npm run mcp # Run CLI commands npm run cli ``` ## 🤝 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. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Barresider](https://github.com/Barresider) - **Source:** [Barresider/x-mcp](https://github.com/Barresider/x-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-barresider-x-mcp - Seller: https://agentstack.voostack.com/s/barresider - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.