x-use

Browser-native AI agents for X (Twitter). Multi-account, MCP-ready, no X API key required.

x-use uses an async Patchright Chromium browser authenticated with your own X session. Its MCP tools cover posts, replies, searches, inbox reads, reviewed messages, follows, local leads, and campaign drafts. Isolated account contexts, browser ownership locks, durable local action budgets, and uncertain-outcome tracking protect shared sessions.

No official X API is used. Write tools stage drafts by default; messages and follows always require individual draft approval. Browser challenges and rate limits pause work for operator recovery. Browser runtime and outreach guide describes setup, limits, recovery, and current limitations.

The detailed runtime audit records the controls, test evidence and remaining compatibility gaps. The tool validation matrix distinguishes live-account results from isolated tests for every registered tool.

x-use 3.0.0 brings reviewed outreach, structured messages and notifications, and seven agent skills. See the migration notes when upgrading from 2.x. Use accounts you own or are authorized to manage.

python -m pip install --upgrade x-use-mcp
python -m patchright install chromium

py -3 scripts/setup_uv.py

iex "& { $(irm https://raw.githubusercontent.com/ihuzaifashoukat/x-use/main/install.ps1) }"

curl -fsSL https://raw.githubusercontent.com/ihuzaifashoukat/x-use/main/install.sh | bash

git clone https://github.com/ihuzaifashoukat/x-use.git
cd x-use
pip install -e .

Point any capable agent at this repository and it can install and configure x-use itself. SKILL.md at the root is the install-and-configure skill: it covers prerequisites, pip install, MCP client registration for Claude Desktop, Claude Code, Codex, Cursor, and Windsurf, the client restart, cookie-based account setup, keywords, and persona.

npx skills add ihuzaifashoukat/x-use

Or paste the one-shot prompt in docs/SETUP_PROMPT.md into your client. Prefer to drive it yourself? Keep reading.

Set up

x-use init     # interactive wizard: presets, account + cookie import, LLM keys
x-use doctor   # verify browser/driver, cookies, LLM keys, proxies

Set X_USE_HOME to an absolute private directory before setup and use the same value in your MCP client environment. PyPI installations include a Patchright starter configuration and an inactive sample account; source checkouts also offer the full preset library. Existing configuration is kept unless you explicitly choose to replace it.

Then connect your AI client. Paste this into claude_desktop_config.json (Claude Desktop > Settings > Developer > Edit Config); the same command/args pair works for any MCP client that runs stdio servers:

{
  "mcpServers": {
    "x-use": {
      "command": "x-use",
      "args": ["mcp"],
      "env": {"X_USE_HOME": "/absolute/path/to/x-use-data"}
    }
  }
}

Replace the X_USE_HOME placeholder with the directory used during setup (Windows paths can use forward slashes, such as C:/Users/you/AppData/Local/x-use). If x-use is not on your client's PATH, use the full path the installer printed (for example .venv/bin/x-use or .venv\Scripts\x-use.exe). Restart the client, then ask it to list_accounts.

Draft mode is on by default. Ordinary publishing tools return a reviewable draft for approve_draft; operators can explicitly disable that mode with "mcp": { "draft_mode": false }. Messages, follows and thread starts still require draft approval. Queue processing, opt-in auto-drain and the legacy batch runner are separate execution paths, so draft mode is not a global prohibition on writes.

MCP tools

The MCP server exposes 70 tools for account and browser status, public timeline and profile reads, inbox, visible analytics availability, reviewed outreach, lead and campaign drafts, action recovery, and resumable X thread workflows. Start profile research with get_profile_context, then use prepare_outreach to stage one personalized DM for review. Use get_thread to read bounded visible conversation context and prepare_thread to stage a multi-post draft. Full references: docs/MCP_GUIDE.md and browser, outreach, and thread guide. Writes use draft review by default; queued work executes through an explicit process_queue call unless the operator enabled auto-drain.

| Group | Tools | |---|---| | Read-only & status | list_accounts, get_account, get_metrics, get_account_analytics, search_tweets, search_profile, get_tweet, prepare_reply, list_queue, list_drafts, get_draft, get_run_status, get_account_health, list_proxies | | Write (draft mode by default) | post_tweet, generate_and_post, reply_to_tweet, engage, approve_draft | | Draft management | reject_draft | | Legacy batch (Selenium only; executes directly) | run_cycle | | Scheduled queue | queue_post, queue_engagement, cancel_queued_action, process_queue | | Composite (server LLM) | research_and_stage, draft_post_variations | | Account management | add_account, update_account, set_account_active, remove_account | | Proxy management | add_proxy, remove_proxy, test_proxy | | X threads | get_thread, prepare_thread, get_thread_run, continue_thread, cancel_thread |

Inbox reads are partial and limited to the currently visible conversations and messages. get_inbox and search_conversations accept folder="inbox"|"requests"|"other", inbox_filter="all"|"unread"|"read", and unread_first. Native Unread selection and visible unread markers carry their evidence in the result; unknown unread state remains unknown. Other requests may be spam or lower priority. Listing requests does not accept them. For older messages in a conversation, pass next_before_message_id from the result as the next call's before_message_id. This cursor only pages the current visible conversation window. Opening a conversation can mark it read.

get_notifications(account="personal", view="all", limit=20) reads structured notifications; use view="mentions" for the Mentions tab. Results include actors, related posts or previews, timestamps, and supported event-type evidence. Unread state and notification IDs stay null when X does not expose them. Reads are bounded and partial, and visiting notifications may mark them read.

get_account_analytics reports only evidenced signed-in-owner analytics availability. The observed screen is an X Premium paywall; it returns premium_required without metrics. Unsupported layouts return unsupported_dom. It does not expose an analytics dashboard or substitute local action metrics from get_metrics.

Interactive use needs no LLM key: your MCP client (Claude, Codex, ...) does the thinking, sees tweet images via get_tweet/prepare_reply, and passes explicit text to the write tools. The optional server-side LLM (llm block) only powers the composite tools, "auto" text, and background automation.

Drafts persist in data/drafts.jsonl; the queue persists in data/engagement_queue.jsonl. Both survive restarts.

MCP prompts and resources

Tools are what the model calls. Prompts and resources are the other two halves of the protocol, and x-use serves both.

Prompts are the workflows, usable in any MCP client. The bundled SKILL.md files only work in clients that implement Agent Skills; these need no installation and show up wherever your client surfaces prompts.

| Prompt | Arguments | What it does | |---|---|---| | research_niche | account, keywords, profiles | Read-only sweep of keywords and watched profiles, scored shortlist, stages nothing | | draft_replies | account, tweet_urls, lane | Stage replies in the account's persona, into drafts or the queue | | review_and_publish | account | Review what is staged and publish only what you approve by id | | daily_check | account | Health, metrics, drafts, and queue in one read-only pass | | setup_account | none | Conversational onboarding from nothing | | outreach_message | account, profile | Verify one profile and prepare one reviewed DM draft | | thread_workflow | account, tweet_url | Read bounded visible context, prepare a reviewed thread, and inspect durable progress |

Resources are read-only context your client can attach without spending a turn. None of them start a browser, and all run the same masking as the tools, so no cookie, password, or proxy credential leaves through them.

| Resource | Type | Contents | |---|---|---| | xuse://accounts | JSON | Every configured account, secrets stripped | | xuse://accounts/{account_id} | JSON | One account's full masked config | | xuse://accounts/{account_id}/persona | Markdown | The account's voice. Attach before writing anything as it | | xuse://drafts/pending | JSON | Everything awaiting approval, with the exact text that would publish |

Agent skills

x-use init (or x-use skills install) installs seven agent skills for Claude Code and Codex: x-use (overview), x-use-setup (onboarding), x-use-engage (research and replies), x-use-inbox (messages, unread/request folders, and notifications), x-use-content (content creation), x-use-review (daily digest), and x-use-threads (thread reading, review, and continuation). For Claude Code, the plugin setup guide covers marketplace installation and local checkout loading with an absolute data directory.

Zero-knowledge setup: paste the prompt from docs/SETUP_PROMPT.md into your AI client, it installs, registers, verifies, and interviews you to configure your account.

CLI

x-use init                            # interactive setup wizard
x-use run                             # all active accounts, concurrent
x-use run --account my_account        # one account only
x-use run --pipeline keyword_replies  # one pipeline only (in-memory; config files untouched)
x-use doctor                          # environment checks; exits non-zero on failure
x-use mcp                             # start the MCP stdio server

Pipelines for --pipeline: community_engagement, competitor_reposts, content_curation, keyword_replies, keyword_retweets, likes. The MCP run_cycle tool accepts the same names.

The legacy python src/main.py entry point remains available through a deprecated compatibility shim. Use x-use run for the legacy batch engine.

Features

| Area | What you get | |---|---| | MCP server | Tools over stdio on the MCP Python SDK (FastMCP, mcp>=1.30,<2 for tool annotations and structured results), including profile context, public connections, inbox, reviewed outreach, persistent leads/campaigns, session recovery, action budgets, and resumable thread workflows. | | Draft mode | On by default. Write tools build the full payload (including LLM-generated text), store a draft, and touch nothing until approve_draft runs. | | Multi-account engine | Post (including communities and media), reply, repost/quote, like, keyword search, and relevance-gated engagement. Per-account overrides for keywords, LLM settings, and action behavior. | | LLM generation | One OpenAI-compatible client (llm: api_key, base_url, model) covers OpenAI, OpenRouter, Azure, Gemini, and local servers. Only needed for "auto" text and background automation; interactive MCP use runs keyless. Keys resolve from env/.env first, then config/settings.json. | | Browser runtime | Async Patchright, isolated contexts, account ownership locks, bounded sessions and explicit challenge recovery. | | Proxies | Per-account routes and named pools; async MCP uses stable account hashing, while round-robin is a legacy batch setting. Proxy strings support ${VAR} interpolation. | | Metrics | Per-account counters in data/metrics/.json plus JSONL event logs in logs/accounts/.jsonl. |

x-use vs. API-based X MCP servers

| | x-use | API-based X/Twitter MCP servers | |---|---|---| | X API cost | $0: cookie auth, no X API key needed | Paid X API tier required | | Multi-account | Built-in: per-account config, cookies, proxies | Typically one account | | Proxies | Per-account proxies, named pools, hash/round-robin rotation | N/A | | Browser management | Isolated Chromium contexts, per-account serialization, cross-process ownership locks | N/A (official API) | | Write safety | Draft mode on by default, explicit approve_draft gate | Usually posts directly | | Metrics | Per-account counters + JSONL event logs, readable via MCP | Varies |

An LLM key is optional: interactive MCP use needs none (your agent writes the text). For "auto" generation and background automation, set one OpenAI-compatible key (llm.api_key + base_url + model, or OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODEL); that is the only key involved.

Configuration

• config/accounts.json: your accounts (gitignored). Start from config/accounts.example.json or let x-use init write it.
• config/settings.json: global defaults for browser, pacing, action caps, LLM, proxies, and the mcp section.
• .env: LLM API keys; overrides settings.json (env wins). See .env.example.

Optional proxy provider

A proxy is optional and does not make an authenticated account anonymous or prevent platform restrictions. If your network needs one, ScrapingAnt offers residential proxy service.

Responsible use

Browser automation of X carries real account risk. Read docs/BEST_PRACTICES.md before running anything: it covers conservative rate limits (the shipped defaults), account warm-up, relevance filters, cookie and credential hygiene, and X ToS considerations. Keep delays high, caps low, and draft mode on.

FAQ

Does x-use need an X (Twitter) API key?

No. x-use drives a real Chrome session authenticated with cookies you export from your own browser, so it never calls the X API and costs $0 in API fees. An LLM key is optional too: interactive MCP use is keyless, because your AI client writes the text and passes it to the tools.

Which MCP clients work with x-use?

Any client that can run a stdio MCP server can use the documented configuration. Claude Desktop, Claude Code, Cursor, and Windsurf are supported by their stdio MCP configuration flows: {"command": "x-use", "args": ["mcp"]}.

How many X accounts can x-use manage?

As many as you configure. Each account carries its own cookies, proxy, persona, keywords, and daily action caps in config/accounts.json, and gets its own browser session from a lazy pool that reaps idle sessions.

Will automating X get my account suspended?

It can, and you should plan for that. x-use ships conservative action spacing and per-action daily caps, with draft review enabled by default. These controls do not guarantee freedom from account restrictions. Read docs/BEST_PRACTICES.md and keep the caps low.

What is the difference between x-use and twitter-automation-ai?

They are the same project. twitter-automation-ai was renamed to x-use for the v2 relaunch, which added the MCP server, the x-use CLI, draft mode, and the PyPI package. Old URLs still redirect, and stars, forks, and issues came across intact.

Is x-use free?

Yes, MIT licensed, installed with pip install x-use-mcp. The only costs are optional: an LLM key if you want server-side text generation, and residential proxies if you run several accounts at once.

Development

pip install -e '.[dev]'
pytest

The regression suite covers MCP contracts, approvals, budgets, uncertainty recovery, browser ownership, inbox state, campaign suppression, setup and the legacy engine. Synthetic browser fixtures use local intercepted responses without personal accounts. CI is configured in .github/workflows/ci.yml for Windows, macOS and Linux on Python 3.10/3.11/3.12/3.13/3.14, locked uv installs, distribution validation, clean-wheel MCP/CLI startup, Chromium smoke runs, and a non-root container. Local Windows checks have been run; remote matrix and container results require a GitHub workflow run.

x-use is published on PyPI and listed in the official MCP Registry as io.github.ihuzaifashoukat/x-use. Container targets and a Claude Code plugin are included; dashboard work and further selector recovery remain on the roadmap.

Contributing

Contributions are welcome. Selector fixes, presets, docs, and MCP tool ideas (via issues) are the most valuable contributions right now. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community expectations.

Star history

MIT. See LICENSE.