mcp-twitter

This MCP server provides a comprehensive integration with X (Twitter) via 53 total tools, including 33 Twitter API tools and 20 enhanced SocialData.tools research tools. It supports both standard Twitter operations (posting, liking, following, getting user information, etc.) and advanced research capabilities such as historical searches, trend analysis, sentiment analysis, and network insights. Tools are exposed via JSON-RPC calls (for example tools/list to enumerate available tools and tools/call to execute a specific tool with arguments). To use the server, ensure your environment is configured with the required API credentials, start the server, and then issue RPC requests to perform actions like retrieving user profiles, posting tweets, or running enhanced research queries. If you have a SocialData.tools API key, you can access the additional 20 enhanced research tools that bypass certain Twitter API tier restrictions and provide richer analytics.

Prerequisites:

• Node.js 18+ installed on your machine
• npm or yarn
• Twitter/X API credentials (Basic tier minimum) and optional SocialData.tools API key

Step 1: Clone the repository

git clone <repository-url>
cd twitter-server

Step 2: Install dependencies

npm install

Step 3: Create and configure environment

cp .env.example .env
# Edit .env and populate credentials:
# X_API_KEY=your_api_key_here
# X_API_SECRET=your_api_secret_here
# X_ACCESS_TOKEN=your_access_token_here
# X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
# Optional: SOCIALDATA_API_KEY=your_socialdata_api_key_here

Step 4: Build and run the server

npm run build
npm start

Step 5: Test via JSON-RPC

# List available tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call a specific tool (example: getUserInfo)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

Tips and common notes:

• The SocialData.tools integration requires an API key; without it, enhanced research tools will provide setup guidance instead of errors.
• Some Twitter API endpoints may be restricted by your account tier; use the enhanced SocialData.tools tools to bypass certain limitations where applicable.
• Ensure you keep credentials secure and do not commit .env files to version control.
• You can adjust environment variables such as SOCIALDATA_BASE_URL to point to alternative endpoints if needed.
• If you encounter 403 errors on certain Twitter endpoints (like getFollowers or getFollowing), verify your account permissions and API access level.