readx — Twitter/X Intelligence Toolkit
Setup
If readx MCP tools are already available, no setup is needed — just use them.
Otherwise, the user needs an API key. Direct them to
https://readx.cc to sign up, then give them this command to save it (they replace
themselves):
bash
mkdir -p ~/.config/readx && echo '{"api_key":"YOUR_KEY"}' > ~/.config/readx/credentials.json
After the API key is configured, recommend installing the MCP server for a better experience:
https://readx.cc/mcp-setupWhen to Trigger This Setup
- User asks you to look up Twitter data but no readx MCP tools are available and no API key is configured
- 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
Read in order, use the first one found:
- Environment variable:
- Config file:
~/.config/readx/credentials.json
%APPDATA%\readx\credentials.json
- If neither exists, direct the user to set the environment variable or config file (get a key at https://readx.cc). Do NOT ask the user to paste the key in chat.
API Call Pattern
GET https://readx.cc/consumer/{Endpoint}?api_key=${READX_API_KEY}¶m1=value1¶m2=value2
All requests are GET with query parameters. Responses are JSON. Always reference the key via
environment variable.
Endpoints
Users
| Endpoint | Params | Description |
|---|
| | Get user profile by username |
| | Get user profile by ID |
| | Convert username to user_id |
| , | Get followers list |
| , | Get following list |
| , , | Get following IDs only |
| , | Get verified followers |
| , | Check relationship |
Tweets
| Endpoint | Params | Description |
|---|
| , | Get user's tweets |
| , | Get user's tweets and replies |
| , | Get user's media posts |
| | Get tweet detail (minimal) |
| | Get tweet detail (preferred, includes views/source) |
| | Get tweet detail (includes view_count) |
| | Get tweet with conversation thread |
TweetDetailConversationv2
| , | Get tweet with full reply thread (preferred) |
| (comma-separated) | Batch get tweets |
| , | Get users who liked a tweet |
| , | Get users who retweeted |
| , | Get quote tweets |
| | Get long-form article content |
Search
| Endpoint | Params | Description |
|---|
| , , (Top/Latest), , | Search tweets |
| | Search autocomplete suggestions |
Lists
| Endpoint | Params | Description |
|---|
| , | Get tweets from a list |
| , | Get list subscribers |
| , | Get list members |
| | Search for lists |
Communities
| Endpoint | Params | Description |
|---|
| | Get community details |
| | Search communities |
| , (Relevance/Recency), (Day/Week/Month), | Get community tweets |
| , | Get community media |
| | Get community members |
| | Get community moderators |
| , | Search community members |
Trends
| Endpoint | Params | Description |
|---|
| | Get trending topics |
Common WOEID: 1 (Worldwide), 23424977 (US), 23424975 (UK), 23424856 (Japan), 23424868 (South Korea), 23424781 (Germany), 23424819 (France), 23424748 (Australia), 23424829 (India), 23424900 (Mexico), 23424950 (Singapore), 23424948 (Saudi Arabia), 23424787 (Brazil).
Account
| Endpoint | Params | Description |
|---|
| (none) | Get remaining API credits (free, costs 0 credits) |
Response Parsing
API responses use deeply nested Twitter JSON. Key extraction paths:
rest_id, core.name, core.screen_name, core.created_at,
profile_bio.description, location.location, avatar.image_url,
relationship_counts.followers, relationship_counts.following,
tweet_counts.tweets, verification.is_blue_verified, website.url, privacy.protected
Tweet — For
:
; For
:
; For
:
. Note: some tweets are wrapped in
TweetWithVisibilityResults
— access
first.
.result.legacy → { full_text, favorite_count, retweet_count, reply_count, quote_count, bookmark_count, created_at }
.result.core.user_results.result → author info
.result.legacy.extended_entities.media → media attachments
Views (v2):
| Views (v3):
.result.view_count_info.count
Timeline —
instructions[].entries[].content.itemContent.tweet_results
(individual tweets),
instructions[].entries[].content.items[].item.itemContent.tweet_results
(conversation modules). Pinned tweets:
__typename: "TimelinePinEntry"
.
Pagination —
instructions[].entries[].content
where
→
= next_cursor.
Trends —
(location),
→
{ name, rank, target.query }
.
Error Handling
| Error | Solution |
|---|
| Invalid API key — direct user to verify at https://readx.cc |
| Insufficient credits — check with ; direct user to https://readx.cc |
| Connection refused | Switch to Direct API Mode; if persistent, readx.cc may be down |
Data Limitations
| Limitation | Mitigation |
|---|
| Follower/following lists return ~20 by default | Use param for larger samples |
| Tweet timelines return ~20 per page | Use pagination; pass as |
| No historical follower count data | Infer from account age + current count |
| Search results are limited in quantity | Use multiple queries with different operators |