Twitter/X MCP

Twitter/X MCP

[CI] [npm version] [npm downloads] [MCP Registry] [License: ISC]

Twitter/X MCP lets an MCP client read public X posts, replies, and profiles, or search X. It uses Rettiwt by default, so you do not need an X developer plan. You can switch to the official X API if you have access.

Requirements

• Node.js 22.21.0 or newer within the Node 22 release line is the declared supported runtime. Node 24 testing and installation limitations are described below.
• A RETTIWT_API_KEY. Official X API credentials work when you select API mode.

Node 24 compatibility

The full project check and all five live MCP tool calls passed on Node.js 24.19.0. CI also runs the full project check on Node 24.

The published package and Rettiwt 7.1.4 still declare engines.node: "^22.21.0". Installing on Node 24 can therefore produce EBADENGINE warnings, and npm rejects the installation when engine-strict is enabled. Use Node 22.21.0 or a newer Node 22 release for installation within the declared supported range. Official Node 24 support remains pending a Rettiwt release that declares Node 24 compatibility and a corresponding update to this package's engine range.

Quick start

Once the package is published, your MCP client can run it without a clone:

npx -y @granitebps/twitter-mcp

The server selects Rettiwt when you omit TWITTER_MODE. Pass RETTIWT_API_KEY in the client configuration.

The server uses stdio. Keep stdout reserved for MCP traffic.

Run from a cloned repository

To develop the server or use a clone directly:

git clone https://github.com/granitebps/twitter-mcp.gitcd twitter-mcpnpm cinpm run build

Point your MCP client at the compiled entry point:

node /absolute/path/to/twitter-mcp/dist/cli.js

Run npm run build after each source change. Do not use src or npm run dev as the client's stdio command. Build logs on stdout can corrupt MCP messages.

Client configuration

Each example starts with the npm package, followed by the local equivalent. Replace /absolute/path/to/twitter-mcp with your clone's path and your_key_here with your Rettiwt key. Do not commit a configuration file that contains the key.

Claude

Add the npm package to Claude Code:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

For a local build:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code uses local scope by default. Add --scope user before twitter to make the server available across projects.

Claude Desktop reads the same server from claude_desktop_config.json. Restart the app after editing the file.

{  "mcpServers": {    "twitter": {      "command": "npx",      "args": ["-y", "@granitebps/twitter-mcp"],      "env": {        "RETTIWT_API_KEY": "your_key_here"      }    }  }}

For a local build, replace command and args with:

{  "command": "node",  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]}

Codex

Add the npm package to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.twitter]command = "npx"args = ["-y", "@granitebps/twitter-mcp"]
[mcp_servers.twitter.env]RETTIWT_API_KEY = "your_key_here"

For a local build:

[mcp_servers.twitter]command = "node"args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]
[mcp_servers.twitter.env]RETTIWT_API_KEY = "your_key_here"

Restart Codex after editing the file. The CLI, IDE extension, and desktop app share this configuration on the same computer.

OpenCode

Add the npm package to opencode.json or opencode.jsonc:

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "twitter": {      "type": "local",      "command": ["npx", "-y", "@granitebps/twitter-mcp"],      "enabled": true,      "environment": {        "RETTIWT_API_KEY": "your_key_here"      }    }  }}

For a local build, replace the command array with:

{  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]}

Cursor

Add the npm package to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for global use:

{  "mcpServers": {    "twitter": {      "command": "npx",      "args": ["-y", "@granitebps/twitter-mcp"],      "env": {        "RETTIWT_API_KEY": "your_key_here"      }    }  }}

For a local build, replace command and args with:

{  "command": "node",  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]}

Providers

Rettiwt setup

Rettiwt requires authenticated user mode in this server. Guest mode is not supported.

1. Generate an API key using the Rettiwt authentication instructions.
2. Store it as RETTIWT_API_KEY in the MCP client's environment.
3. Start the server without TWITTER_MODE, or set TWITTER_MODE=rettiwt explicitly.

A Rettiwt key contains X session cookies and has the same access as the account. Treat it like a password. Do not commit it, paste it into an issue, log it, or pass it as a command-line argument. Use a key only for an account you own or have permission to access.

Rettiwt is unofficial. X's automation rules prohibit non-API website automation and warn that violations may lead to account suspension. Read the X Rules before using this mode. You accept the compliance and account risk.

Official X API setup

Use a bearer token:

TWITTER_MODE=apiTWITTER_BEARER_TOKEN=your_bearer_token

Or provide the complete OAuth set:

TWITTER_MODE=apiTWITTER_API_KEY=your_api_keyTWITTER_API_SECRET=your_api_secretTWITTER_ACCESS_TOKEN=your_access_tokenTWITTER_ACCESS_SECRET=your_access_secret

Create credentials in the X Developer Portal. X controls API access and pricing, so check the current terms before choosing this mode.

Configuration

The server rejects an incomplete OAuth configuration at startup. It reads credentials from the process environment and never returns them through get_server_info.

Tools

max_results defaults to 10 and accepts 1 through 100. Successful calls return structured MCP content plus JSON text for older clients. Collection tools return the items as JSON text and put cursors and warnings in structured content.

In Rettiwt mode, posts returned by get_tweet, get_tweet_replies, and search_tweets also include an optional media array when the provider supplies it. Each item contains id, type (PHOTO, VIDEO, or GIF), a direct url, and an optional thumbnail_url for video previews. The server returns media links; it does not download the files. Official API mode does not currently return attached media.

The v1 compatibility contract records the stable tool, input, output, and error behavior for the 1.x release line.

Errors

Tool failures use stable codes:

• INVALID_INPUT
• AUTH_REQUIRED
• AUTH_FAILED
• NOT_FOUND
• RATE_LIMITED
• UPSTREAM_UNAVAILABLE
• TIMEOUT
• UNSUPPORTED_OPERATION
• INTERNAL_ERROR

Errors name the provider and tell the client whether a retry may work. They do not include credentials or raw upstream response bodies.

Architecture

stdio CLI  -> validated environment configuration  -> MCP server and tool handlers  -> TwitterProvider contract       -> Rettiwt adapter       -> official X API adapter

The domain schemas do not depend on either provider. Each provider adapter maps upstream data, enforces limits and deadlines, and translates errors. Importing src/index.ts does not start the server.

Development

npm cinpm run check

npm run check checks formatting, lint, types, coverage, the production build, npm package contents, and a clean tarball installation. The default test suite uses fakes and does not need X credentials.

Useful focused commands:

npm testnpm run typechecknpm run lintnpm run buildnpm run check:packagenpm run check:installnpx @modelcontextprotocol/inspector node dist/cli.js

Live Rettiwt smoke test

The live smoke test starts the compiled stdio server and calls get_tweet, get_tweet_replies, get_user_profile, and search_tweets. It derives the username and search query from the selected post.

RETTIWT_API_KEY=your_key_here \TWITTER_LIVE_TWEET_ID=1234567890123456789 \npm run test:live

Choose a public post whose author profile is still available. If either variable is missing, the command stops before starting the live server or making a network request. It does not run as part of npm run check or normal CI.

Release verification

The automated suite covers configuration, provider adapters, MCP calls, the compiled stdio entry point, and installation from an npm tarball. The live Rettiwt smoke test is optional and does not run in normal CI. Version 1.0.0 was prepared without live upstream verification.

Maintainers can follow the release guide for the approved-tag npm, MCP Registry, and GitHub release process. Live tests must read credentials from repository secrets and must not run for untrusted pull requests.

Troubleshooting

Missing Rettiwt key

If startup reports RETTIWT_API_KEY is required in rettiwt mode, set the key in the MCP client configuration. Desktop clients do not automatically inherit a shell's .env file.

Invalid Rettiwt authentication

If you see Invalid authentication data or AUTH_FAILED, generate a new Rettiwt key and check that the X session still works. Never post the failing key in an issue.

Rate limit

For RATE_LIMITED, wait before retrying and reduce the request rate. Check retryAfterSeconds when the provider supplies it.

Official API 401 or 403

Confirm the credential set, app permissions, endpoint access, and current X API plan.

Node engine warning

Run Node.js 22.21.0 or a newer Node 22 release to satisfy the package and Rettiwt engine ranges. Node 24.19.0 passed runtime testing, but installations on Node 24 can warn or fail under engine-strict; see Node 24 compatibility.

License

ISC