{"_id":"@cochatai/x-mcp-server","_rev":"2-7e9f127e96f52e853591a6c81dd62111","name":"@cochatai/x-mcp-server","dist-tags":{"latest":"1.1.2"},"versions":{"1.1.1":{"name":"@cochatai/x-mcp-server","version":"1.1.1","keywords":["mcp","mcp-server","modelcontextprotocol","server","twitter","x","twitter-api","x-api","claude","claude-ai","oauth","oauth2","social-media","tweet","api"],"author":{"name":"Enes Cinar"},"license":"MIT","_id":"@cochatai/x-mcp-server@1.1.1","maintainers":[{"name":"cochat","email":"marcel@cochat.ai"}],"homepage":"https://github.com/Cochat/x-mcp-server#readme","bugs":{"url":"https://github.com/Cochat/x-mcp-server/issues"},"bin":{"x-server":"build/index.js"},"dist":{"shasum":"1e6ac19e64f3d142f96944010d463e95c17897ed","tarball":"https://registry.npmjs.org/@cochatai/x-mcp-server/-/x-mcp-server-1.1.1.tgz","fileCount":12,"integrity":"sha512-jx1xN8LqjGSDBQRNulHxUzeU5Lnlz20dmR/xVZl2OVluHYCfdK4liP1ftxNEueJBM2hzsEQ0G6zYfdRUmfc14g==","signatures":[{"sig":"MEQCIBp1h54Hfpub5EURyvlGTyYippukLDA/hQh1aLosnKpeAiAWFLnwLkG5WKfTqQEZFOqb8/z2rRhAVRXK77Vznf7CEA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66422},"main":"build/index.js","type":"module","gitHead":"caa3f5ccb1237e5910770dff527b0b033d379813","scripts":{"dev":"npm run build && node build/index.js","lint":"tsc --noEmit","test":"jest tests/unit","build":"tsc","start":"node build/index.js","format":"prettier --write \"src/**/*.ts\"","test:all":"jest","build:dxt":"node scripts/build-dxt.js","test:unit":"jest tests/unit","test:watch":"jest --watch","test:coverage":"jest --coverage tests/unit","prepublishOnly":"npm run build","test:functional":"jest tests/functional","test:integration":"jest tests/integration"},"_npmUser":{"name":"cochat","email":"marcel@cochat.ai"},"repository":{"url":"git+https://github.com/Cochat/x-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"Enhanced MCP server for X with OAuth 2.0 support, media uploads, and LLM-friendly rate limiting.","directories":{},"_nodeVersion":"20.20.0","dependencies":{"zod":"^3.24.0","dotenv":"^16.4.7","mcp-evals":"^1.0.18","twitter-api-v2":"^1.18.2","@modelcontextprotocol/sdk":"0.6.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.3","open":"^10.1.2","chalk":"^5.4.1","ts-jest":"^29.4.0","archiver":"^7.0.1","typescript":"^5.3.3","@types/jest":"^30.0.0","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/x-mcp-server_1.1.1_1770219987830_0.12023066289101991","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"@cochatai/x-mcp-server","version":"1.1.2","description":"Enhanced MCP server for X with OAuth 2.0 support, media uploads, and LLM-friendly rate limiting.","type":"module","main":"build/index.js","bin":{"x-server":"build/index.js"},"scripts":{"build":"tsc","start":"node build/index.js","dev":"npm run build && node build/index.js","test":"jest tests/unit","test:all":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage tests/unit","test:unit":"jest tests/unit","test:integration":"jest tests/integration","test:functional":"jest tests/functional","lint":"tsc --noEmit","format":"prettier --write \"src/**/*.ts\"","prepublishOnly":"npm run build","build:dxt":"node scripts/build-dxt.js"},"keywords":["mcp","mcp-server","modelcontextprotocol","server","twitter","x","twitter-api","x-api","claude","claude-ai","oauth","oauth2","social-media","tweet","api"],"author":{"name":"Enes Cinar"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"0.6.0","dotenv":"^16.4.7","mcp-evals":"^1.0.18","twitter-api-v2":"^1.18.2","zod":"^3.24.0"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^20.11.24","archiver":"^7.0.1","chalk":"^5.4.1","jest":"^30.0.3","open":"^10.1.2","ts-jest":"^29.4.0","typescript":"^5.3.3"},"repository":{"type":"git","url":"git+https://github.com/Cochat/x-mcp-server.git"},"bugs":{"url":"https://github.com/Cochat/x-mcp-server/issues"},"homepage":"https://github.com/Cochat/x-mcp-server#readme","publishConfig":{"access":"public"},"_id":"@cochatai/x-mcp-server@1.1.2","gitHead":"32002817ecf11dccff5c5e940876aad222302132","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tGHHDIcGf1Xp0bcLA3SEeEkNbu2JarKuxJ+4PYT9P+pYHgLLOm9E/9KY1ZbFiv/0o/PtIFZJsvSkEImS7KIC+Q==","shasum":"92e819ce6ac5b26621ed3b1871d2ed1e464cfa27","tarball":"https://registry.npmjs.org/@cochatai/x-mcp-server/-/x-mcp-server-1.1.2.tgz","fileCount":12,"unpackedSize":71202,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCkVRCqQQzxloftm2W6f3kaRNfSuC1JaBVCkoubUh2tYwIhAIBcM9GX93ZLyCu2+sTJJt7SsTsL0twy9YUn+JiazLpr"}]},"_npmUser":{"name":"cochat","email":"marcel@cochat.ai"},"directories":{},"maintainers":[{"name":"cochat","email":"marcel@cochat.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x-mcp-server_1.1.2_1770226420706_0.09833346205710214"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-04T15:46:27.708Z","modified":"2026-02-04T17:33:40.988Z","1.1.1":"2026-02-04T15:46:27.979Z","1.1.2":"2026-02-04T17:33:40.874Z"},"bugs":{"url":"https://github.com/Cochat/x-mcp-server/issues"},"author":{"name":"Enes Cinar"},"license":"MIT","homepage":"https://github.com/Cochat/x-mcp-server#readme","keywords":["mcp","mcp-server","modelcontextprotocol","server","twitter","x","twitter-api","x-api","claude","claude-ai","oauth","oauth2","social-media","tweet","api"],"repository":{"type":"git","url":"git+https://github.com/Cochat/x-mcp-server.git"},"description":"Enhanced MCP server for X with OAuth 2.0 support, media uploads, and LLM-friendly rate limiting.","maintainers":[{"name":"cochat","email":"marcel@cochat.ai"}],"readme":"# X MCP Server - Enhanced Edition\n\n[![npm version](https://badge.fury.io/js/@mbelinky%2Fx-mcp-server.svg)](https://www.npmjs.com/package/@mbelinky/x-mcp-server)\n\nAn enhanced Model Context Protocol (MCP) server for X that adds OAuth 2.0 support, v2 API media uploads, and comprehensive rate limiting to the original implementation.\n\n## ✨ Features\n\n- **Post Tweets**: Create text tweets with optional media attachments (images, GIFs)\n- **Search Tweets**: Search X with customizable result count\n- **Delete Tweets**: Remove your tweets programmatically\n- **Dual Authentication**: Support for both OAuth 1.0a and OAuth 2.0\n- **Media Upload**: Post images using the appropriate API version for each auth method\n- **Rate Limiting**: Built-in protection for X's API limits\n- **Type Safety**: Full TypeScript implementation with Zod validation\n\n## 🔄 API Version Handling\n\nThis server intelligently uses different X API versions based on authentication method and operation:\n\n### OAuth 1.0a\n- **Tweet operations**: Uses v2 API endpoints\n- **Media upload**: Uses v1.1 endpoint (`upload.twitter.com`)\n- **Delete fallback**: Automatically falls back to v1.1 when v2 fails\n\n### OAuth 2.0\n- **All operations**: Uses v2 API endpoints exclusively\n- **Media upload**: Uses v2 endpoint (`api.x.com/2/media/upload`)\n- **No v1.1 access**: Cannot fall back to v1.1 due to authentication restrictions\n\n### Why Different Endpoints?\n- **v1.1**: Legacy API, being phased out but still works with OAuth 1.0a\n- **v2**: Modern API with better features but some endpoints have issues\n- **Media**: OAuth 2.0 tokens cannot access v1.1 media endpoints, must use v2\n- **Delete**: v2 delete endpoint currently has issues (500 errors), v1.1 works as fallback\n\n## 📋 Prerequisites\n\nBefore you begin, you'll need:\n\n1. An X Developer Account (sign up at [developer.x.com](https://developer.x.com))\n2. An X App created in the Developer Portal\n3. API credentials (detailed setup below)\n4. Node.js 18+ installed\n\n## 🔐 Authentication Setup\n\nThis server supports two authentication methods. Choose based on your needs:\n\n- **OAuth 1.0a**: Simpler setup, works with all features including v1.1 fallbacks\n- **OAuth 2.0**: Modern authentication, required for some newer features\n\n### Setting Up Your X App\n\n1. **Create a Developer Account**:\n   - Go to [developer.x.com](https://developer.x.com)\n   - Sign in with your Twitter account\n   - Apply for developer access if you haven't already\n\n2. **Create a New App**:\n   - Navigate to the [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)\n   - Click \"Projects & Apps\" → \"New Project\"\n   - Give your project a name\n   - Select your use case\n   - Create a new App within the project\n\n3. **Configure App Permissions**:\n   - In your app settings, go to \"User authentication settings\"\n   - Click \"Set up\"\n   - Enable OAuth 1.0a and/or OAuth 2.0\n   - Set App permissions to \"Read and write\"\n   - Add Callback URLs:\n     - For OAuth 1.0a: `http://localhost:3000/callback`\n     - For OAuth 2.0: `http://localhost:3000/callback`\n   - Set Website URL (can be your GitHub repo)\n\n### OAuth 1.0a Setup\n\n1. **Get Your Credentials**:\n   - In your app's \"Keys and tokens\" tab\n   - Copy your API Key and API Key Secret\n   - Generate Access Token and Secret (click \"Generate\")\n   - Make sure the access token has \"Read and Write\" permissions\n\n2. **Required Credentials**:\n   ```\n   API_KEY=your_api_key_here\n   API_SECRET_KEY=your_api_secret_key_here\n   ACCESS_TOKEN=your_access_token_here\n   ACCESS_TOKEN_SECRET=your_access_token_secret_here\n   ```\n\n### OAuth 2.0 Setup\n\n1. **Get Your Client Credentials**:\n   - In your app's \"Keys and tokens\" tab\n   - Find OAuth 2.0 Client ID and Client Secret\n   - Save these for the next step\n\n2. **Generate User Tokens**:\n   \n   Option A - Use our helper script:\n   ```bash\n   # Clone this repository first\n   git clone https://github.com/mbelinky/x-mcp-server.git\n   cd x-mcp-server/twitter-mcp\n   npm install\n   \n   # Run the OAuth2 setup script\n   node scripts/oauth2-setup.js\n   ```\n   \n   Option B - Manual setup:\n   - Use the OAuth 2.0 flow with PKCE\n   - Required scopes: `tweet.read`, `tweet.write`, `users.read`, `media.write`, `offline.access`\n   - Exchange authorization code for access token\n\n3. **Required Credentials**:\n   ```\n   AUTH_TYPE=oauth2\n   OAUTH2_CLIENT_ID=your_client_id_here\n   OAUTH2_CLIENT_SECRET=your_client_secret_here\n   OAUTH2_ACCESS_TOKEN=your_access_token_here\n   OAUTH2_REFRESH_TOKEN=your_refresh_token_here\n   ```\n\n## 🚀 Installation\n\n### For Claude Desktop\n\n1. **Install via NPM** (Recommended):\n\n   Edit your Claude Desktop configuration file:\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n   Add this configuration:\n   ```json\n   {\n     \"mcpServers\": {\n       \"twitter-mcp\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@mbelinky/x-mcp-server\"],\n         \"env\": {\n           \"API_KEY\": \"your_api_key_here\",\n           \"API_SECRET_KEY\": \"your_api_secret_key_here\",\n           \"ACCESS_TOKEN\": \"your_access_token_here\",\n           \"ACCESS_TOKEN_SECRET\": \"your_access_token_secret_here\"\n         }\n       }\n     }\n   }\n   ```\n\n   For OAuth 2.0:\n   ```json\n   {\n     \"mcpServers\": {\n       \"twitter-mcp\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@mbelinky/x-mcp-server\"],\n         \"env\": {\n           \"AUTH_TYPE\": \"oauth2\",\n           \"OAUTH2_CLIENT_ID\": \"your_client_id\",\n           \"OAUTH2_CLIENT_SECRET\": \"your_client_secret\",\n           \"OAUTH2_ACCESS_TOKEN\": \"your_access_token\",\n           \"OAUTH2_REFRESH_TOKEN\": \"your_refresh_token\"\n         }\n       }\n     }\n   }\n   ```\n\n2. **Install from Source**:\n   ```bash\n   git clone https://github.com/mbelinky/x-mcp-server.git\n   cd x-mcp-server/twitter-mcp\n   npm install\n   npm run build\n   ```\n\n   Then update your config to point to the local installation:\n   ```json\n   {\n     \"mcpServers\": {\n       \"twitter-mcp\": {\n         \"command\": \"node\",\n         \"args\": [\"/path/to/twitter-mcp/build/index.js\"],\n         \"env\": {\n           // ... your credentials\n         }\n       }\n     }\n   }\n   ```\n\n3. Restart Claude Desktop\n\n### For Claude Code (CLI)\n\nInstall the server globally and add it to Claude:\n\n```bash\n# For OAuth 1.0a\nclaude mcp add twitter-mcp \"npx\" \"-y\" \"@mbelinky/x-mcp-server\" --scope user \\\n  --env \"API_KEY=your_api_key\" \\\n  --env \"API_SECRET_KEY=your_secret_key\" \\\n  --env \"ACCESS_TOKEN=your_access_token\" \\\n  --env \"ACCESS_TOKEN_SECRET=your_access_token_secret\"\n\n# For OAuth 2.0\nclaude mcp add twitter-mcp \"npx\" \"-y\" \"@mbelinky/x-mcp-server\" --scope user \\\n  --env \"AUTH_TYPE=oauth2\" \\\n  --env \"OAUTH2_CLIENT_ID=your_client_id\" \\\n  --env \"OAUTH2_CLIENT_SECRET=your_client_secret\" \\\n  --env \"OAUTH2_ACCESS_TOKEN=your_access_token\" \\\n  --env \"OAUTH2_REFRESH_TOKEN=your_refresh_token\"\n```\n\n## 🛠️ Available Tools\n\nOnce installed, Claude can use these tools:\n\n### `post_tweet`\nPost a new tweet with optional media attachments and replies.\n\nExample prompts:\n- \"Post a tweet saying 'Hello from Claude!'\"\n- \"Tweet this image with the caption 'Check out this view!'\" (attach image)\n- \"Reply to tweet ID 123456789 with 'Great point!'\"\n\n### `search_tweets`\nSearch for tweets with customizable result count (10-100).\n\nExample prompts:\n- \"Search for tweets about #MachineLearning\"\n- \"Find 50 recent tweets mentioning @ClaudeAI\"\n- \"Search for tweets about TypeScript tutorials\"\n\n### `delete_tweet`\nDelete a tweet by its ID.\n\nExample prompts:\n- \"Delete tweet with ID 1234567890\"\n- \"Remove my last tweet (provide the ID)\"\n\nNote: Due to temporary Twitter API issues, OAuth 1.0a uses v1.1 fallback for deletion.\n\n### 📸 Media Upload Notes\n\nWhen using Claude to post tweets with images:\n- **Use file paths**: Save your image to disk and provide the file path\n- **Base64 limitation**: While the server supports base64 encoded images, Claude cannot extract base64 from pasted images\n- **Other clients**: Base64 support remains available for programmatic use and other MCP clients\n\nExample usage:\n```\n# ✅ Recommended for Claude\n\"Post tweet with image at /Users/me/photos/sunset.png\"\n\n# ❌ Not currently supported in Claude\n\"Post this image: [pasting an image directly]\"\n\n# ✅ Works programmatically\n// In code, you can still use base64\n{\n  \"text\": \"Hello world!\",\n  \"media\": [{\n    \"data\": \"iVBORw0KGgoAAAANS...\",\n    \"media_type\": \"image/png\"\n  }]\n}\n```\n\n## 🧪 Testing\n\nThe project includes comprehensive tests:\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suites\nnpm test -- --testNamePattern=\"OAuth\"\nnpm test -- --testPathPattern=\"unit\"\n```\n\n## 🔧 Development\n\n### Setup\n```bash\ngit clone https://github.com/mbelinky/x-mcp-server.git\ncd x-mcp-server/twitter-mcp\nnpm install\n```\n\n### Commands\n```bash\nnpm run build    # Build TypeScript\nnpm run dev      # Run in development mode\nnpm test         # Run tests\nnpm run lint     # Lint code\nnpm run format   # Format code\n```\n\n### Environment Variables\nCreate a `.env` file for local development:\n```env\n# OAuth 1.0a\nAPI_KEY=your_api_key\nAPI_SECRET_KEY=your_api_secret_key\nACCESS_TOKEN=your_access_token\nACCESS_TOKEN_SECRET=your_access_token_secret\n\n# OAuth 2.0 (if using)\nAUTH_TYPE=oauth2\nOAUTH2_CLIENT_ID=your_client_id\nOAUTH2_CLIENT_SECRET=your_client_secret\nOAUTH2_ACCESS_TOKEN=your_access_token\nOAUTH2_REFRESH_TOKEN=your_refresh_token\n\n# Optional\nDEBUG=true  # Enable debug logging\n```\n\n## ✅ OAuth 2.0 Media Upload Support\n\n**Media uploads now work with both OAuth 1.0a and OAuth 2.0!**\n- OAuth 1.0a uses the v1.1 media upload endpoint ✓\n- OAuth 2.0 uses the v2 media upload endpoint ✓\n- Both authentication methods support posting tweets with images (JPEG, PNG, GIF)\n\nNote: OAuth 2.0 requires the `media.write` scope for media uploads.\n\n## ⚠️ Known Issues\n\n### Tweet Deletion (Temporary)\nTwitter's v2 delete endpoint is currently experiencing issues (returning 500 errors). The MCP server handles this gracefully:\n- **OAuth 1.0a**: Automatically falls back to v1.1 delete endpoint ✅\n- **OAuth 2.0**: Cannot use v1.1 endpoint, will show helpful error message ⚠️\n\nThis is a temporary Twitter API issue. Once resolved, both auth methods will use v2 deletion.\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"Could not authenticate you\"**\n- Verify all credentials are correct\n- Check that your app has \"Read and Write\" permissions\n- For OAuth 1.0a, regenerate your access tokens\n- For OAuth 2.0, ensure tokens have required scopes\n\n**\"Rate limit exceeded\"**\n- Twitter has strict rate limits (especially on free tier)\n- Wait 15 minutes and try again\n- Consider upgrading your Twitter API access level\n\n**\"Media upload failed\"**\n- Check file size (max 5MB for images)\n- Verify file format (JPEG, PNG, GIF only)\n- For OAuth 2.0, ensure `media.write` scope is included\n\n**\"403 Forbidden\"**\n- Your app may lack required permissions\n- Check your Twitter Developer Portal settings\n- Ensure your access level supports the operation\n\n### Debug Mode\nEnable detailed logging by setting the `DEBUG` environment variable:\n```json\n{\n  \"env\": {\n    \"DEBUG\": \"true\",\n    // ... other credentials\n  }\n}\n```\n\n### Log Locations\n- Windows: `%APPDATA%\\Claude\\logs\\mcp-server-twitter.log`\n- macOS: `~/Library/Logs/Claude/mcp-server-twitter.log`\n\n## 📚 Resources\n\n- [Twitter API Documentation](https://developer.twitter.com/en/docs/twitter-api)\n- [MCP Documentation](https://modelcontextprotocol.io)\n- [OAuth 2.0 Setup Guide](https://developer.twitter.com/en/docs/authentication/oauth-2-0)\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## 🔒 Privacy Policy\n\nThis MCP server:\n- **Does not store any user data**: All Twitter/X API credentials are stored locally on your machine\n- **Does not log sensitive information**: API keys and tokens are never logged\n- **Only communicates with Twitter/X**: No data is sent to any third-party services\n- **Processes data locally**: All operations happen on your machine\n- **Respects rate limits**: Built-in protection for Twitter's API limits\n\nYour tweets, searches, and media remain private between you and Twitter/X.\n\n## 📧 Support\n\n- **Email**: mbelinky@gmail.com\n- **Issues**: [GitHub Issues](https://github.com/mbelinky/x-mcp-server/issues)\n- **Documentation**: [GitHub Wiki](https://github.com/mbelinky/x-mcp-server/wiki)\n\nFor security vulnerabilities, please email directly instead of creating a public issue.\n\n## 📄 License\n\nMIT\n\n## 🙏 Acknowledgments\n\nThis is an enhanced fork of [@enescinar/twitter-mcp](https://github.com/EnesCinr/twitter-mcp) that adds:\n- OAuth 2.0 authentication support\n- Twitter/X API v2 media upload for OAuth 2.0\n- Automatic v1.1 fallback for OAuth 1.0a\n- Comprehensive rate limiting for free tier\n- Enhanced error handling and debugging\n- Programmatic OAuth 2.0 token generation script\n\nOriginal implementation by [@enescinar](https://github.com/EnesCinr)","readmeFilename":"README.md"}