{"_id":"@barresider/x-mcp","name":"@barresider/x-mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@barresider/x-mcp","version":"1.0.1","private":false,"description":"A Model Context Protocol (MCP) server that provides unofficial X/Twitter API access through browser automation using Playwright","main":"dist/mcp.js","bin":{"x-mcp":"dist/mcp.js"},"scripts":{"build":"tsc","mcp":"ts-node -T ./src/mcp.ts","cli":"ts-node -T ./src/cli.ts","prepublishOnly":"npm run build","prepack":"npm run build","release":"release-it"},"keywords":["mcp","model-context-protocol","twitter","x","playwright","automation","social-media","ai-tools"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Barresider/x-mcp.git"},"bugs":{"url":"https://github.com/Barresider/x-mcp/issues"},"homepage":"https://github.com/Barresider/x-mcp#readme","publishConfig":{"access":"public"},"engines":{"node":">=18.0.0"},"devDependencies":{"@playwright/test":"^1.44.0","@release-it/conventional-changelog":"^8.0.1","@tsconfig/recommended":"^1.0.6","@types/commander":"^2.12.0","@types/node":"^20.12.12","release-it":"^17.6.0","ts-node":"^10.9.2","typescript":"^5.4.5"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","@types/express":"^5.0.2","commander":"^12.1.0","dotenv":"^16.4.5","express":"^5.1.0","playwright":"^1.44.0","zod":"^3.25.36"},"_id":"@barresider/x-mcp@1.0.1","gitHead":"4b719abe2197edcb19ac27418a7edc95672efaae","types":"./dist/mcp.d.ts","_nodeVersion":"20.17.0","_npmVersion":"10.8.3","dist":{"integrity":"sha512-wAg4GfLQjLaLStipGwI22indd1fdQ9TM7/TZ4umB+j3IWAKSHGcSaezkt/aeZkkL2hTgGd2lv9+NnSf6U/UrbQ==","shasum":"1019a9f6f8665bbf52a76a9bfcc60ddba70f8ea3","tarball":"https://registry.npmjs.org/@barresider/x-mcp/-/x-mcp-1.0.1.tgz","fileCount":41,"unpackedSize":155439,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICvn1CMvxjdVM7AYVqnUL482taU7RnDe+6aVzNWrv3N1AiEAqvHkDZE0XdIKql82u/Pxib2O3EMpZnvojszXQovNVF0="}]},"_npmUser":{"name":"barresider","email":"barresider@web.de"},"directories":{},"maintainers":[{"name":"barresider","email":"barresider@web.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x-mcp_1.0.1_1748535093307_0.4288742279958775"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-29T16:11:33.204Z","1.0.1":"2025-05-29T16:11:33.567Z","modified":"2025-05-29T16:11:33.913Z"},"maintainers":[{"name":"barresider","email":"barresider@web.de"}],"description":"A Model Context Protocol (MCP) server that provides unofficial X/Twitter API access through browser automation using Playwright","homepage":"https://github.com/Barresider/x-mcp#readme","keywords":["mcp","model-context-protocol","twitter","x","playwright","automation","social-media","ai-tools"],"repository":{"type":"git","url":"git+https://github.com/Barresider/x-mcp.git"},"bugs":{"url":"https://github.com/Barresider/x-mcp/issues"},"license":"MIT","readme":"# X/Twitter MCP Server\n\nA 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.\n\n## 🚀 Features\n\n### Content Creation & Interaction\n- **Tweet & Thread Posting**: Post single tweets or multi-tweet threads with media support\n- **Post Interactions**: Like, unlike, retweet, unretweet, bookmark, quote tweet, and reply to posts\n- **Comment Management**: Like, unlike, reply to, and edit comments\n- **Media Support**: Upload and attach images, videos, and GIFs to tweets\n\n### Content Scraping & Analysis\n- **Timeline Scraping**: Extract posts from \"For You\" and \"Following\" timelines\n- **Profile Scraping**: Get comprehensive user profile data and recent posts\n- **Search Functionality**: Advanced search with filters for viral content, specific users, and date ranges\n- **Comment Scraping**: Extract comments and replies from specific posts\n- **Trending Topics**: Retrieve current trending topics and hashtags\n\n### MCP Integration\n- **Dual Transport Support**: Works with both stdio and HTTP/SSE transports\n- **Tool-based Interface**: 20+ tools available for AI agents to interact with X/Twitter\n- **Structured Responses**: JSON-formatted responses with comprehensive metadata\n- **Error Handling**: Robust error handling with descriptive error messages\n\n## 📋 Prerequisites\n\n- Node.js 18+ \n- Valid X/Twitter account credentials\n- Docker (optional, for containerized deployment)\n\n## Quick Start\n\n1. Add this configuration to your Claude Desktop config file:\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`  \n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"x-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@barresider/x-mcp\"],\n      \"env\": {\n        \"TWITTER_USERNAME\": \"your_twitter_username\",\n        \"TWITTER_PASSWORD\": \"your_twitter_password\"\n      }\n    }\n  }\n}\n```\n\n2. Restart Claude Desktop\n\nThat's it! Claude can now interact with X/Twitter through 25+ powerful tools including:\n\n- `tweet`: Post a new tweet with optional media\n- `thread`: Post a multi-tweet thread\n- `search_twitter`: Search for tweets with advanced filters\n- `scrape_profile`: Get comprehensive user profile data\n- `scrape_timeline`: Extract posts from timelines\n- `like_post`, `retweet_post`, `bookmark_post`: Interact with posts\n- And many more for comprehensive X/Twitter automation\n\n## Example Usage\n\nTry asking Claude:\n- \"Can you post a tweet saying 'Hello from Claude!'\"\n- \"Can you search for tweets about Claude AI?\"\n- \"Can you scrape Elon Musk's profile and show me his latest 5 tweets?\"\n- \"Can you post a thread about the benefits of AI?\"\n\n## 🛠️ Installation\n\n### Local Development Installation\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd x-mcp\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the project:\n```bash\nnpm run build\n```\n\n### Docker Installation\n\n1. Build the Docker image:\n```bash\ndocker build -t x-mcp .\n```\n\n2. Or use Docker Compose:\n```bash\ndocker-compose --profile mcp up --build\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root:\n\n```env\n# Required: X/Twitter credentials\nTWITTER_USERNAME=your_username\nTWITTER_PASSWORD=your_password\n\n# Optional: MCP server configuration\nMCP_TRANSPORT=stdio           # Options: stdio, sse, http\nMCP_PORT=3000                # Port for HTTP/SSE transport\n```\n\n### Authentication Setup\n\n1. Create authentication directory:\n```bash\nmkdir -p playwright/.auth\n```\n\n2. Login to X/Twitter (stores session for reuse):\n```bash\nnpm run cli login\n# or\nnode dist/cli.js login\n```\n\n## 🔧 Available MCP Tools\n\nThe server provides 25+ tools for comprehensive X/Twitter interaction:\n\n### Authentication & Setup\n- `login` - Authenticate with X/Twitter\n\n### Content Creation\n- `tweet` - Post a single tweet with optional media\n- `thread` - Post a multi-tweet thread\n- `reply_to_post` - Reply to a specific post\n- `quote_tweet` - Quote tweet with additional text\n\n### Post Interactions\n- `like_post` / `unlike_post` - Like/unlike posts\n- `retweet_post` / `unretweet_post` - Retweet/unretweet posts\n- `bookmark_post` / `unbookmark_post` - Bookmark management\n\n### Comment Interactions\n- `like_comment_by_id` / `unlike_comment_by_id` - Like/unlike comments\n- `reply_to_comment_by_id` - Reply to comments\n- `replace_comment_by_id` - Edit comments (if supported)\n\n### Content Scraping\n- `scrape_posts` - Scrape posts from current page\n- `scrape_profile` - Get user profile and recent posts\n- `scrape_comments` - Extract comments from posts\n- `scrape_timeline` - Scrape For You/Following timelines\n- `scrape_trending` - Get trending topics\n- `search_twitter` - General search functionality\n- `search_viral` - Search for viral content with minimum engagement\n\n## 📊 Data Structures\n\n### TwitterPost\n```typescript\ninterface TwitterPost {\n  postId: string;\n  author: TwitterUser;\n  content: string;\n  timestamp: Date;\n  media: TwitterMedia[];\n  metrics: PostMetrics;\n  engagementRate: number;\n  isRetweet?: boolean;\n  retweetedFrom?: TwitterUser;\n  quotedPost?: TwitterPost;\n  url: string;\n}\n```\n\n### TwitterProfile\n```typescript\ninterface TwitterProfile extends TwitterUser {\n  bannerUrl?: string;\n  bio?: string;\n  location?: string;\n  website?: string;\n  joinedDate?: Date;\n  followingCount: number;\n  followersCount: number;\n  postsCount: number;\n  isFollowing?: boolean;\n  isFollowedBy?: boolean;\n  latestPosts?: TwitterPost[];\n}\n```\n\n### PostMetrics\n```typescript\ninterface PostMetrics {\n  likesCount: number;\n  retweetsCount: number;\n  quotesCount: number;\n  repliesCount: number;\n  impressionsCount: number;\n  bookmarksCount: number;\n}\n```\n\n## 🔒 Security & Best Practices\n\n### Rate Limiting\n- Implement delays between requests to avoid rate limiting\n- Use reasonable limits for scraping operations\n- Monitor for rate limit responses\n\n### Authentication\n- Store credentials securely in environment variables\n- Session data is stored in `playwright/.auth/` directory\n- Regular re-authentication may be required\n\n### Error Handling\n- All operations include comprehensive error handling\n- Descriptive error messages for troubleshooting\n- Graceful degradation for missing elements\n\n## 🐳 Docker Deployment\n\n### Using Docker Compose\n```bash\n# Start the MCP server\ndocker-compose --profile mcp up\n\n# With environment variables\nTWITTER_USERNAME=your_username TWITTER_PASSWORD=your_password docker-compose --profile mcp up\n```\n\n### Custom Docker Run\n```bash\ndocker run -d \\\n  --name x-mcp \\\n  -e TWITTER_USERNAME=your_username \\\n  -e TWITTER_PASSWORD=your_password \\\n  -e MCP_TRANSPORT=sse \\\n  -e MCP_PORT=3000 \\\n  -p 3000:3000 \\\n  x-mcp\n```\n\n## 🛠️ Development\n\n### Project Structure\n```\nsrc/\n├── mcp.ts                    # Main MCP server implementation\n├── cli.ts                    # Command line interface\n├── types.ts                  # TypeScript type definitions\n├── utils.ts                  # Utility functions\n├── behaviors/                # User interaction behaviors\n│   ├── login.ts             # Authentication logic\n│   ├── interact-with-post.ts # Post interaction functions\n│   ├── interact-with-comment.ts # Comment interaction functions\n│   └── upload-media.ts      # Media upload functionality\n└── scrapers/                # Data scraping modules\n    ├── index.ts             # Scraper exports\n    ├── post-scraper.ts      # Post scraping logic\n    ├── profile-scraper.ts   # Profile scraping logic\n    ├── comment-scraper.ts   # Comment scraping logic\n    ├── search-scraper.ts    # Search functionality\n    ├── timeline-scraper.ts  # Timeline scraping\n    └── utils.ts             # Scraping utilities\n```\n\n### Building and Testing\n```bash\n# Build TypeScript\nnpm run build\n\n# Run MCP server\nnpm run mcp\n\n# Run CLI commands\nnpm run cli <command>\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n### Guidelines\n- Follow TypeScript best practices\n- Add comprehensive error handling\n- Update type definitions for new features\n- Test with real X/Twitter interactions\n- Document new functionality\n\n## ⚠️ Disclaimers\n\n- This is an unofficial tool using browser automation\n- X/Twitter's terms of service apply\n- Use responsibly and respect rate limits\n- UI changes may require updates to selectors\n- Not affiliated with X/Twitter\n\n## 📄 License\n\n[License information here]\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Authentication Failures**\n- Verify credentials in `.env` file\n- Try logging in again with `npm run cli login`\n- Check for 2FA requirements\n\n**Element Not Found Errors**\n- X/Twitter may have updated their UI\n- Clear browser cache and re-authenticate\n- Check for element selector updates\n\n**Rate Limiting**\n- Reduce request frequency\n- Add delays between operations\n- Use smaller batch sizes\n\n**Container Issues**\n- Ensure proper environment variables\n- Check port availability\n- Verify Docker network configuration\n\nFor more help, please open an issue on the project repository.\n","readmeFilename":"README.md","_rev":"1-dd14cdbd4d53156d92d186eac24d1bb8"}