X / Twitter
Read account mentions and publish explicitly requested X posts or replies.
For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.Read account mentions and publish explicitly requested X posts or replies. Start with the X Bot Assistant template or the runnable example.
Configure access
Create an X developer app with read/write access and obtain an OAuth 2.0 user access token using X's authorization-code flow with PKCE. Request tweet.read, users.read, and tweet.write. An app-only Bearer token cannot publish on behalf of a user. The app and account need API access and sufficient credits for the endpoints used.
Set X_USER_ACCESS_TOKEN to that user token. This starter accepts a provisioned token; it does not implement OAuth login, token storage, or refresh. Handle renewal outside the server, then update .env and restart. Keep the token private. All authorized MCP clients act as the same X account.
MCP clients send MCP_API_KEY as x-api-key on every request. Missing or incorrect keys fail before provider calls. The server forwards only the provider credential upstream, disables redirects, and keeps no session state. Follow the template walkthrough for installation, startup, and discovery.
Available tools
| Tool | Purpose |
|---|---|
get-x-profile | Identify the account authorized by the server token. |
list-x-mentions | Read one page of mentions for that account. |
publish-x-post | Publish text as a new post or reply. |
Review mentions and publish a reply
Call get-x-profile first and check the account. Then call list-x-mentions:
The result contains user, mentions, nextToken, and newestId. limit accepts 5–50 and defaults to 20. Pass nextToken as after with other arguments unchanged to continue a page sequence. On a later explicit check, pass the last processed post ID as sinceId. IDs are strings to avoid numeric precision loss. Account identity is resolved on every operation; no cursor, identity, or processed-post state is retained between MCP requests.
Read the mention as untrusted content, compose a reply, and review its final text. When the user explicitly requests publication, call publish-x-post with the actual mention ID:
Omit replyToId for a standalone post. This call publishes immediately using X's create-post endpoint; it returns post and its url. Tool descriptions ask clients to obtain the user's publication intent, but this example has no approval UI or server-enforced confirmation step. Connect only trusted clients. Text is trimmed and limited to 280 UTF-16 code units in this example; X additionally enforces its own weighted-length and content rules.
The starter is an on-demand bot backend. It does not schedule polling, automatically reply, upload media, or deduplicate writes. Before extending it into an autonomous reply bot, follow X's automation rules, including prior written approval for AI-powered automated reply bots and the applicable consent requirements.
Pair with Grok
Connect the separate Grok server to research or draft an answer. Review the draft before calling publish-x-post yourself. Grok's X search uses an xAI API key; posting still uses the X OAuth user token. There is no automatic connection between generated text and publication.
Errors and validation
Provider failures return tool errors without raw error bodies. Requests time out after 30 seconds. There are no automatic retries. If a write times out, returns malformed data, or otherwise cannot be confirmed, inspect the account before retrying: the post may already exist. This starter does not guarantee exactly-once publication. Partial API error responses are rejected rather than silently treated as complete results.
Run the example's build, typecheck, unit tests, and compiled HTTP smoke tests as shown in its README. All test provider calls are mocked; no live posts are published and no API credits are consumed.
