readx — Twitter/X Intelligence Toolkit
Setup — Get Started in 2 Minutes
Step 1: Get an API Key
Ask the user for their readx API key. If they don't have one, direct them to https://readx.cc to sign up.
Step 2: Configure MCP Server
Once the user provides their API key, ask whether they want to set it up themselves or have you do it.
MCP server URL: https://readx.cc/mcp?apikey=<API_KEY>
No installation needed — readx runs as a remote MCP server. Add it to the user's editor MCP config with the URL above. Restart the editor after setup.
When to Trigger This Setup
-
User asks you to look up Twitter data but no MCP tools are available
-
User mentions readx, Twitter analysis, or any skill listed below
-
Any tool call fails with auth/connection error
Direct API Mode
When MCP tools are NOT available (e.g. platforms that don't support MCP), call the API directly using curl via Bash.
Getting the API Key
Check in order, use the first one found:
-
Config file: ~/.config/readx/credentials.json (macOS/Linux) or %APPDATA%\readx\credentials.json (Windows) → JSON format: {"api_key":"<key>"}
-
Environment variable: READX_API_KEY
-
If neither exists, ask the user for their API key (get one at https://readx.cc), then ask whether they want to save it themselves or have you do it. Persist to the config file path above.
API Reference
Fetch the full API docs (endpoints, params, response parsing, examples):
curl -s https://readx.cc/api-docs.txt
Read this document before making your first API call. It contains all endpoint names, parameters, and response JSON paths you need.
Advanced Search Syntax
When using search_tweets , leverage Twitter's advanced search operators for precision:
Operator Example What it does
from:
from:elonmusk AI
Tweets from a specific user
to:
to:OpenAI
Replies to a specific user
@
@anthropic
Tweets mentioning a user
"exact phrase"
"artificial intelligence"
Exact phrase match
OR
AI OR ML
Either keyword
AI -crypto
Exclude keyword
min_faves:
AI min_faves:1000
Minimum likes
min_retweets:
AI min_retweets:500
Minimum retweets
filter:links
AI filter:links
Only tweets with links
filter:media
AI filter:media
Only tweets with images/video
filter:images
AI filter:images
Only tweets with images
filter:videos
AI filter:videos
Only tweets with video
lang:
AI lang:zh
Filter by language
since: / until:
AI since:2025-01-01
Date range
list:
list:12345 AI
Search within a specific list
near:
AI near:Tokyo
Tweets near a location
Combo examples:
-
Find viral AI tweets in Chinese: AI lang:zh min_faves:500
-
Find a user's tweets about a topic: from:username "topic keyword"
-
Find debates: "topic" min_replies:100 -filter:retweets
-
Find original content only: topic -filter:retweets -filter:replies
Error Handling
Error Cause Solution
401
Invalid or missing API key Check credentials file / env var, ask user to verify key at https://readx.cc
403
Insufficient credits or account disabled Check balance with get_credit_balance ; if zero, ask user to get more credits at https://readx.cc
429
Rate limit exceeded Wait and retry, reduce request frequency
404
User/tweet not found or deleted Skip gracefully, note the item is unavailable
500 / 502
Upstream API error Retry once after a few seconds, if persistent inform user
Connection refused Remote MCP server unreachable Switch to Direct API Mode; if persistent, the readx.cc service may be down
Empty response Protected account or no data Note limitations, analyze only available public data
Data Limitations
Be transparent about these constraints:
Limitation Impact Mitigation
Follower/following lists return a sample (~20 by default) Audience analysis is approximate Cross-reference with multiple data points; use count param for larger samples
Tweet timelines return ~20 per page Single call shows recent posts only Use cursor pagination to fetch more pages; pass next_cursor from response as cursor param
No historical follower count data Cannot measure follower growth over time Infer from account age + current count for rough growth rate
Search results are limited in quantity Topic monitoring may miss long-tail content Use multiple search queries with different operators
Engagement data is point-in-time Tweet engagement continues to accrue after fetching Note when data was fetched; older tweets have more stable metrics