X Tools for Claude MCP

# X Tools for Claude MCP A lightweight, open-source toolkit that enables Claude to search Twitter efficiently with natural language and display results based on user intent. Designed for both raw data viewing and optional analysis. ## Features - **Natural Language Search**: Ask Claude to search Twitter in plain English - **Twitter Search**: Search tweets using natural language or advanced Twitter syntax - **Professional Formatting**: Clean, markdown-formatted tweet display - **Flexible Output**: Display raw tweets or add analysis based on what you ask for - **Advanced Filtering**: Find tweets by keywords, users, dates, engagement metrics, and more - **Pagination Support**: Retrieve more than the default 20 tweets per search when needed ## Installation ### Prerequisites - Node.js v16+ - Claude for Desktop - Free RapidAPI key with access to the "The Old Bird API" (Twitter154) endpoint ### RapidAPI Key Setup 1. Visit [The Old Bird API on RapidAPI](https://rapidapi.com/omarmhaimdat/api/twitter154) 2. Sign up for a RapidAPI account if you don't have one 3. Subscribe to the API (there is a free tier available) 4. Once subscribed, copy your RapidAPI key from your dashboard ### Setup Steps 1. **Clone this repository**: ```bash git clone https://github.com/0xGval/twitter-X-mcp-server cd twitter-X-mcp-tools ``` 2. **Install dependencies**: ```bash npm install ``` 3. **Create your configuration**: - Copy `mcp.json.example` to `mcp.json` in your Claude Desktop directory - Edit `mcp.json` to include your RapidAPI key and correct file paths ```json { "mcpServers": { "x-tools": { "command": "node", "args": ["YOUR_ABSOLUTE_PATH_TO/main.js"], "env": { "RAPIDAPI_KEY": "your_rapidapi_key" } } } } ``` 4. **Configure Claude for Desktop**: - On Windows: Place your `mcp.json` file in `%APPDATA%\Claude\` - On macOS: Place your `mcp.json` file in `~/Library/Application Support/Claude/` - Copy `claude-rules.md` and `knowledge/TwitterSearchSyntaxGuide.txt` to your Claude knowledge base directory - Restart Claude Desktop for the changes to take effect ## Available Tools ### Twitter Search The tool is primarily designed to be used with natural language. Simply ask Claude to search for something on Twitter, and it will interpret your request. ``` searchTwitter(query: "keyword", section: "latest", limit: 20) ``` Search Twitter using natural language or advanced syntax: - `query`: Search query (supports Twitter's advanced search operators) - `section`: "latest" or "top" results (default: "latest") - `limit`: Number of tweets to return (default: 20) ## Natural Language Examples ### Simple Query Ask Claude: ``` Show me recent tweets about artificial intelligence ``` ### User-Focused Query Ask Claude: ``` Find the latest tweets from Elon Musk that mention SpaceX ``` ### Complex Natural Query Ask Claude: ``` Search for tweets about climate change with at least 100 likes from the past month ``` ### Analysis Request Ask Claude: ``` What's the sentiment around the new Bitcoin ETF based on recent tweets? ``` ## Direct Syntax Examples For those who prefer direct syntax: ``` from:elonmusk spacex since:2023-01-01 ``` ``` "artificial intelligence" filter:images min_faves:100 ``` ``` climate action min_retweets:50 -filter:retweets ``` ## Required Files This tool includes several important files that must be properly set up: - **main.js**: The main application file - **tools/twitter.js**: The Twitter search implementation - **claude-rules.md**: Instructions for Claude to display search results appropriately - **knowledge/TwitterSearchSyntaxGuide.txt**: Reference guide for Twitter search syntax Make sure all these files are placed in the correct locations in your Claude setup. ## Search Syntax The tool supports all standard Twitter search operators, which Claude can apply from your natural language: ### Users - `from:username` - Tweets sent by a specific account - `to:username` - Replies to a specific account - `@username` - Tweets mentioning the account ### Media and Links - `filter:media` - Tweets with any media - `filter:images` - Tweets with images - `filter:native_video` - Tweets with videos - `filter:links` - Tweets with links ### Dates - `since:YYYY-MM-DD` - Tweets after this date - `until:YYYY-MM-DD` - Tweets before this date ### Engagement - `min_retweets:n` - Tweets with at least n retweets - `min_faves:n` - Tweets with at least n likes - `min_replies:n` - Tweets with at least n replies ## Troubleshooting Common issues: - **API Key Not Found**: Ensure your RapidAPI key is correctly set in `mcp.json` - **Path Errors**: Make sure you're using full absolute paths with proper escaping in Windows (`\\`) - **No Results**: Check that your search query is valid and not too restrictive - **Claude Behavior Issues**: Make sure you have the latest version of `claude-rules.md` that includes the flexible output instructions - **Missing Files**: Verify that `claude-rules.md` and `TwitterSearchSyntaxGuide.txt` are properly added to your Claude rules and knowledge base ## Development To modify the tool: 1. Edit the files in the `tools/` directory 2. Update the formatting in `formatTwitterResults()` function if needed 3. Restart Claude for Desktop to see changes ## License This project is licensed under the MIT License. ## Acknowledgements - Model Context Protocol (MCP) by Anthropic - RapidAPI Twitter154 API - Axios - Zod --- **Note**: This tool is designed to work with the Claude AI assistant and provide Twitter search results with flexible display options based on user intent.