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 YOUR_KEY themselves):

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-setup

When 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:

1. Environment variable: READX_API_KEY
2. Config file: ~/.config/readx/credentials.json (macOS/Linux) or %APPDATA%\readx\credentials.json (Windows) → {"api_key":"..."}
3. 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}&param1=value1&param2=value2

All requests are GET with query parameters. Responses are JSON. Always reference the key via ${READX_API_KEY} environment variable.

Endpoints

Users

Tweets

Search

Lists

Communities

Trends

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

Response Parsing

Note: This section is only for Direct API Mode. MCP tools already return clean, extracted data — no manual parsing needed.

API responses use deeply nested Twitter JSON. Key extraction paths:

User profile — data.user_results.result:

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 TweetDetail: data.tweet_result; For TweetDetailv2: data.tweetResult; For TweetDetailv3: data.tweet_results. Note: some tweets are wrapped in TweetWithVisibilityResults — access .tweet 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): .result.views.count | 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 cursor_type = "Bottom" → .value = next_cursor.

Trends — metadata.woeid.name (location), modules[].trend → { name, rank, target.query }.

Credit balance — { credits: <number> }.

Error Handling

Data Limitations