Content
# 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 <repository-url>
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 <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.
