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
- Visit The Old Bird API on RapidAPI
- Sign up for a RapidAPI account if you don't have one
- Subscribe to the API (there is a free tier available)
- Once subscribed, copy your RapidAPI key from your dashboard
Setup Steps
-
Clone this repository:
git clone https://github.com/0xGval/twitter-X-mcp-server cd twitter-X-mcp-tools -
Install dependencies:
npm install -
Create your configuration:
- Copy
mcp.json.exampletomcp.jsonin your Claude Desktop directory - Edit
mcp.jsonto include your RapidAPI key and correct file paths
{ "mcpServers": { "x-tools": { "command": "node", "args": ["YOUR_ABSOLUTE_PATH_TO/main.js"], "env": { "RAPIDAPI_KEY": "your_rapidapi_key" } } } } - Copy
-
Configure Claude for Desktop:
- On Windows: Place your
mcp.jsonfile in%APPDATA%\Claude\ - On macOS: Place your
mcp.jsonfile in~/Library/Application Support/Claude/ - Copy
claude-rules.mdandknowledge/TwitterSearchSyntaxGuide.txtto your Claude knowledge base directory - Restart Claude Desktop for the changes to take effect
- On Windows: Place your
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 accountto:username- Replies to a specific account@username- Tweets mentioning the account
Media and Links
filter:media- Tweets with any mediafilter:images- Tweets with imagesfilter:native_video- Tweets with videosfilter:links- Tweets with links
Dates
since:YYYY-MM-DD- Tweets after this dateuntil:YYYY-MM-DD- Tweets before this date
Engagement
min_retweets:n- Tweets with at least n retweetsmin_faves:n- Tweets with at least n likesmin_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.mdthat includes the flexible output instructions - Missing Files: Verify that
claude-rules.mdandTwitterSearchSyntaxGuide.txtare properly added to your Claude rules and knowledge base
Development
To modify the tool:
- Edit the files in the
tools/directory - Update the formatting in
formatTwitterResults()function if needed - 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.