# ExTweets

Agentic X/Twitter Tools

ExTweets is an independent MCP server for AI agents that need user-authorized access to X/Twitter account actions and Grok-backed research.

Base URL: https://extweets.com
MCP endpoint: https://extweets.com/mcp
Human setup page: https://extweets.com/
LLM discovery file: https://extweets.com/llms.txt

This service is not affiliated with, endorsed by, or sponsored by X Corp, Twitter, xAI, or Grok.

## How an agent should use this service

1. Direct the human to add the MCP endpoint `https://extweets.com/mcp` to an OAuth-capable MCP client.
2. The MCP client discovers the authorization server, registers at `https://extweets.com/register`, and sends the human through `https://extweets.com/authorize`.
3. The human approves access with X/Twitter OAuth. The MCP client receives access tokens from `https://extweets.com/token`.
4. The human does not manually copy a static API token in the current flow.
5. The agent should call `list_x_accounts` before taking account-specific actions.
6. If multiple accounts are connected, every X API tool call must include the `account` parameter.
7. For write actions, the agent should state the target account and action before calling the tool.
8. Tool responses include the account used, for example `used_account`, `posted_from`, or `sent_from`.
9. For research, prefer `ask_grok_x` or `ask_grok_web` instead of scraping X/Twitter pages.

## Account selection

- Call `list_x_accounts` first.
- Use the returned `username` or `userId` as the `account` value.
- If exactly one X account is connected, ExTweets can infer it.
- If multiple X accounts are connected, ExTweets rejects ambiguous X API calls that omit `account`.
- Grok research tools do not require `account` because they call xAI rather than acting as a connected X account.

## Authentication model

- MCP resource endpoint: `https://extweets.com/mcp`
- OAuth authorization endpoint: `https://extweets.com/authorize`
- OAuth token endpoint: `https://extweets.com/token`
- Dynamic client registration endpoint: `https://extweets.com/register`
- Current model: OAuth-managed MCP access tokens issued to compatible clients after human authorization.
- Planned dashboard model: a signed-in ExTweets account can manage connected accounts, billing, revocation, and possibly create named MCP credentials for clients that do not support dynamic OAuth well.

## Cloudflare MCP runtime

- Transport: Streamable HTTP on Cloudflare Workers.
- MCP server mode: authenticated remote MCP.
- Auth provider: Cloudflare Workers OAuth Provider Library.
- Current runtime: Agents SDK `McpAgent`, which creates a Durable Object-backed session runtime.
- Architecture note: if ExTweets remains mostly stateless API tools, `createMcpHandler()` is the simpler Cloudflare path to evaluate before a broader public launch.

## Safety model

- X/Twitter account access uses OAuth and can be revoked by the user.
- Tools operate only through connected accounts.
- X API tools accept an `account` selector and require it when more than one account is connected.
- Tool responses include which connected account was used.
- X connection tokens are stored encrypted while an account remains connected so ExTweets can execute user-requested MCP actions.
- Temporary OAuth login state expires shortly after authorization.
- Grok research uses ExTweets server-side xAI API access and is not tied to a selected X account.
- Connected-account custody and agent actions are separate safety concerns.
- Custody controls: OAuth, encrypted token payloads, revocation, no static user-copied secrets, and no raw tokens returned to tools.
- Agent controls: per-client scopes, per-account permissions, spend caps, write-rate limits, high-risk action gates, audit logs, anomaly locks, and instant revoke.

## Grok research

- `ask_grok_x`: Ask Grok to research current X/Twitter posts using xAI X Search.
- `ask_grok_web`: Ask Grok to research the web using xAI Web Search.

## Connected accounts

- `list_x_accounts`: List the X/Twitter accounts connected to the current MCP user.
- `set_default_x_account`: Choose which connected account is used when no account is specified.

## Read and search

- `search_tweets`: Search recent posts with standard X search syntax.
- `get_tweet`: Fetch one post by ID.
- `get_user_profile`: Look up a public profile by username.
- `get_my_profile`: Inspect the selected connected account.
- `get_user_timeline`: Fetch recent posts from a public user timeline.
- `get_home_timeline`: Fetch the selected account's home timeline.
- `get_bookmarks`: Fetch bookmarks for the selected connected account.

## Account actions

- `post_tweet`: Post from a selected connected account.
- `reply_to_tweet`: Reply from a selected connected account.
- `delete_tweet`: Delete a post from a selected connected account.
- `like_tweet`: Like a post from a selected connected account.
- `unlike_tweet`: Remove a like from a selected connected account.
- `follow_user`: Follow a user from a selected connected account.
- `unfollow_user`: Unfollow a user from a selected connected account.
- `bookmark_tweet`: Bookmark a post from a selected connected account.
- `unbookmark_tweet`: Remove a bookmark from a selected connected account.
- `send_dm`: Send a direct message from a selected connected account.

## Provider setup

- Google OAuth callback: https://extweets.com/api/auth/callback/google
- Better Auth X/Twitter sign-in callback: https://extweets.com/api/auth/callback/twitter
- X OAuth callback: https://extweets.com/callback