X Reader Codex Plugin

X Reader is an EyrieCommander Codex plugin fork of xdevplatform/xmcp. It runs a local FastMCP server that exposes a small, read-oriented X API toolset to Codex, so agents can read posts, quoted posts, users, recent search results, and API usage without scraping X in a browser.

This fork keeps the upstream X API MCP server intact while adding:

• Codex plugin metadata
• a source-portable plugin launcher
• a default read-only tool allowlist
• bearer-token mode for read-only local use
• safer token logging defaults

Prerequisites

• Python 3.10+ for direct pip installs, or uv for automatic Python 3.12 environment creation
• An X Developer Platform app (to get tokens)
• Optional: an xAI API key if you want to run the Grok test client

Codex plugin files

This fork can be used directly as a Codex plugin. The plugin files live in:

• .codex-plugin/plugin.json
• .mcp.json
• codex/run-mcp.sh
• skills/x-reader/SKILL.md

For local use:

1. Create .env from env.example.
2. Set X_BEARER_TOKEN.
3. Keep X_AUTH_MODE=bearer for read-only post/profile lookups without an OAuth browser flow.
4. Keep the default X_API_TOOL_ALLOWLIST for read-only Codex use unless you intentionally need more tools.

The plugin launcher creates .venv on first run. If uv is installed, it uses Python 3.12 automatically. Otherwise it looks for Python 3.10+. You can override with XMCP_PYTHON=/path/to/python or XMCP_VENV=/path/to/venv.

Testing

1. Direct launcher smoke test

From the repo root:

./codex/run-mcp.sh

With an existing local venv:

XMCP_VENV=.venv312 ./codex/run-mcp.sh

Expected result: FastMCP starts at http://127.0.0.1:8000/mcp and lists the allowlisted read tools.

2. MCP client smoke test

In another terminal while the server is running:

.venv312/bin/python -c 'import asyncio
from fastmcp import Client
async def main():
    async with Client("http://127.0.0.1:8000/mcp") as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools])
asyncio.run(main())'

Expected result:

['getOpenApiSpec', 'getPostsByIds', 'searchPostsRecent', 'getPostsById', 'getPostsQuotedPosts', 'getUsage', 'getUsersByIds', 'getUsersByUsernames', 'getUsersByUsername', 'getUsersById', 'getUsersPosts']

3. Post lookup smoke test

Call getPostsById through the MCP client with a public post id. For quoted posts, fetch the referenced quoted id as a second call.

Setup (local)

1. Create a virtual environment and install dependencies:
   • python -m venv .venv
   • source .venv/bin/activate
   • pip install -r requirements.txt
2. Create your local .env:
   • cp env.example .env
   • Required values (do not skip):
     • X_OAUTH_CONSUMER_KEY
     • X_OAUTH_CONSUMER_SECRET
     • X_BEARER_TOKEN (required for this setup; keep it set even if using OAuth1)
     • X_AUTH_MODE (bearer for read-only bearer-token mode, oauth1 for browser OAuth1)
   • OAuth1 callback (defaults are fine):
     • X_OAUTH_CALLBACK_HOST (default 127.0.0.1)
     • X_OAUTH_CALLBACK_PORT (default 8976)
     • X_OAUTH_CALLBACK_PATH (default /oauth/callback)
     • X_OAUTH_CALLBACK_TIMEOUT (default 300)
   • Server settings (optional):
     • X_API_BASE_URL (default https://api.x.com)
     • X_API_TIMEOUT (default 30)
     • MCP_HOST (default 127.0.0.1)
     • MCP_PORT (default 8000)
     • X_API_DEBUG (default 1)

• Tool filtering (optional, comma-separated):
  • X_API_TOOL_ALLOWLIST
• Optional Grok test client:
  • XAI_API_KEY
  • XAI_MODEL (default grok-4-1-fast)
  • MCP_SERVER_URL (default http://127.0.0.1:8000/mcp)
• Optional OAuth2 token generation:
  • CLIENT_ID
  • CLIENT_SECRET
  • X_OAUTH_ACCESS_TOKEN - X_OAUTH_ACCESS_TOKEN_SECRET (optional)
• Optional OAuth1 debug output:
  • X_OAUTH_PRINT_TOKENS
  • X_OAUTH_PRINT_AUTH_HEADER

3. Register the callback URL in your X Developer App:

http://<X_OAUTH_CALLBACK_HOST>:<X_OAUTH_CALLBACK_PORT><X_OAUTH_CALLBACK_PATH>

Example (defaults):

http://127.0.0.1:8976/oauth/callback

4. Start the server:

python server.py

The MCP endpoint is http://127.0.0.1:8000/mcp by default.

5. Connect an MCP client:

• Local client: point it to http://127.0.0.1:8000/mcp.
• Remote client: tunnel your local server (e.g., ngrok) and use the public URL.

Whitelisting tools

Use X_API_TOOL_ALLOWLIST to load a small, explicit set of tools:

X_API_TOOL_ALLOWLIST=getUsersByUsername,createPosts,searchPostsRecent

Whitelisting is applied at startup when the OpenAPI spec is loaded, so restart the server after changes. See the full tool list below before building your allowlist.

OAuth1 flow (startup behavior)

When X_AUTH_MODE=oauth1, the server opens a browser for OAuth1 consent and waits for the callback. Tokens are kept in memory only for the lifetime of the server process. Set X_OAUTH_PRINT_TOKENS=1 to print tokens, or X_OAUTH_PRINT_AUTH_HEADER=1 to print request headers.

When X_AUTH_MODE=bearer, the server uses X_BEARER_TOKEN directly and does not launch the OAuth browser flow.

Available tool calls (allowlist-ready)

Below is the full list of tool calls you can whitelist via X_API_TOOL_ALLOWLIST. Copy any of these into your .env allowlist.

• addListsMember
• addUserPublicKey
• appendMediaUpload
• blockUsersDms
• createCommunityNotes
• createComplianceJobs
• createDirectMessagesByConversationId
• createDirectMessagesByParticipantId
• createDirectMessagesConversation
• createLists
• createMediaMetadata
• createMediaSubtitles
• createPosts
• createUsersBookmark
• deleteActivitySubscription
• deleteAllConnections
• deleteCommunityNotes
• deleteConnectionsByEndpoint
• deleteConnectionsByUuids
• deleteDirectMessagesEvents
• deleteLists
• deleteMediaSubtitles
• deletePosts
• deleteUsersBookmark
• evaluateCommunityNotes
• finalizeMediaUpload
• followList
• followUser
• getAccountActivitySubscriptionCount
• getActivitySubscriptions
• getChatConversation
• getChatConversations
• getCommunitiesById
• getComplianceJobs
• getComplianceJobsById
• getConnectionHistory
• getDirectMessagesEvents
• getDirectMessagesEventsByConversationId
• getDirectMessagesEventsById
• getDirectMessagesEventsByParticipantId
• getInsights28Hr
• getInsightsHistorical
• getListsById
• getListsFollowers
• getListsMembers
• getListsPosts
• getMarketplaceHandleAvailability
• getMediaAnalytics
• getMediaByMediaKey
• getMediaByMediaKeys
• getMediaUploadStatus
• getNews
• getOpenApiSpec
• getPostsAnalytics
• getPostsById
• getPostsByIds
• getPostsCountsAll
• getPostsCountsRecent
• getPostsLikingUsers
• getPostsQuotedPosts
• getPostsRepostedBy
• getPostsReposts
• getSpacesBuyers
• getSpacesByCreatorIds
• getSpacesById
• getSpacesByIds
• getSpacesPosts
• getTrendsByWoeid
• getTrendsPersonalizedTrends
• getUsage
• getUserPublicKeys
• getUsersAffiliates
• getUsersBlocking
• getUsersBookmarkFolders
• getUsersBookmarks
• getUsersBookmarksByFolderId
• getUsersById
• getUsersByIds
• getUsersByUsername
• getUsersByUsernames
• getUsersFollowedLists
• getUsersFollowers
• getUsersFollowing
• getUsersLikedPosts
• getUsersListMemberships
• getUsersMe
• getUsersMentions
• getUsersMuting
• getUsersOwnedLists
• getUsersPinnedLists
• getUsersPosts
• getUsersRepostsOfMe
• getUsersTimeline
• hidePostsReply
• initializeMediaUpload
• likePost
• mediaUpload
• muteUser
• pinList
• removeListsMemberByUserId
• repostPost
• searchCommunities
• searchCommunityNotesWritten
• searchEligiblePosts
• searchNews
• searchPostsAll
• searchPostsRecent
• searchSpaces
• searchUsers
• sendChatMessage
• unblockUsersDms
• unfollowList
• unfollowUser
• unlikePost
• unmuteUser
• unpinList
• unrepostPost
• updateActivitySubscription
• updateLists

Generate an OAuth2 user token (optional)

1. Add CLIENT_ID and CLIENT_SECRET to your .env.
2. Update redirect_uri in generate_authtoken.py to match your app settings.
3. Run python generate_authtoken.py and follow the prompts.
4. Copy the printed access token into .env as X_OAUTH_ACCESS_TOKEN. If your flow returns a secret, store it as X_OAUTH_ACCESS_TOKEN_SECRET.

Run the Grok MCP test client (optional)

1. Set XAI_API_KEY in .env.
2. Make sure your MCP server is running locally (or set MCP_SERVER_URL).
3. If Grok is not running on your machine, use ngrok to expose your local MCP server and set MCP_SERVER_URL to the public HTTPS URL that ends with /mcp. Example flow: ngrok http 8000 then MCP_SERVER_URL=https://<id>.ngrok-free.dev/mcp.
4. Run python test_grok_mcp.py.

Notes

• Endpoints with /stream or /webhooks in the path are excluded.
• Operations tagged Stream or Webhooks, or marked with x-twitter-streaming: true, are excluded.
• The OpenAPI spec is fetched from https://api.twitter.com/2/openapi.json at startup.