name: x-use description: Install, register, and configure x-use, the browser-native MCP server for X (Twitter) automation that needs no X API key. Covers pip install, MCP client registration for Claude Desktop, Claude Code, Codex, Cursor and Windsurf, cookie-based account setup, keywords, and persona. Use when the user wants to set up x-use, add an X account, connect X or Twitter automation to their agent, or when x-use tools are unavailable or unconfigured.

Set up x-use

x-use is an MCP server that automates X (Twitter) through a real logged-in Chrome session instead of the paid X API. This skill takes a machine from nothing to a configured, working account.

Read this first: the steps split at the client restart. Everything before it is shell work, because x-use's MCP tools do not exist yet. Everything after it is tool work. Do not try to call add_account before step 4 has completed.

Explain each step in one line as you go, and confirm before anything that changes the user's system.

1. Check the prerequisites

Python 3.10 or newer, and Google Chrome. Check both:

python --version

If either is missing, say so and stop. There is no workaround: x-use drives a real Chrome window, and that is the whole design.

2. Install

pip install x-use-mcp

This provides the x-use command. If the user is working inside a clone of the repository instead, pip install -e . from the repo root does the same thing.

Then verify:

x-use doctor

doctor prints one PASS, FAIL, or SKIP line per check: config files, browser binary, driver, per-account cookies, LLM key, proxies. On a fresh machine the cookie and config checks are expected to fail, since nothing is configured yet. Do not treat that as a broken install. A FAIL on the browser or driver line is the one that actually blocks progress.

If x-use is not found after installing, it is a PATH problem, not a failed install. pip show -f x-use-mcp locates the console script; use its full path everywhere below, for example venv/bin/x-use or venv\Scripts\x-use.exe.

3. Install the workflow skills

x-use skills install

This writes five skills to ~/.claude/skills/ and ~/.agents/skills/, so Claude Code and Codex-style agents both pick them up. They cover engagement, content, daily review, and account setup. --force overwrites existing copies, and x-use skills list shows what landed.

4. Register the MCP server, then restart the client

Work out which client you are running inside and register x-use in that one. The config is identical everywhere: command x-use, args ["mcp"].

• Claude Code:

  claude mcp add x-use -- x-use mcp
  

• Claude Desktop (claude_desktop_config.json), Cursor, Windsurf, and any other client taking JSON:

  {
    "mcpServers": {
      "x-use": {
        "command": "x-use",
        "args": ["mcp"]
      }
    }
  }
  

• Codex (~/.codex/config.toml):

  [mcp_servers.x-use]
  command = "x-use"
  args = ["mcp"]
  

Now tell the user to restart the client, and stop. A stdio MCP server is loaded at client startup, so nothing you do will make the tools appear in the current session. When they come back, confirm the connection with list_accounts. An empty list is the correct answer at this point.

5. Add the account

Everything from here is MCP tool calls.

Ask for a short account id, something like main or brand. It is an internal label, not the X handle.

Then walk the user through the cookie export, which is how x-use authenticates:

1. Install a cookie-export browser extension, for example Cookie-Editor.
2. Log into x.com in that browser.
3. Open the extension while on x.com and export as JSON.
4. Save the file on this machine and give you the path.

add_account(account_id="main", cookie_file="/path/to/cookies.json")

The file is validated and copied server-side. Never ask the user to paste cookie contents into the conversation. The path-only design exists precisely so the values never cross the wire, and pasting them defeats it.

Verify with get_account_health("main"). Cookie status should be valid. If it is not, the export is stale or from the wrong domain, so have them redo it while actually logged in.

6. Configure the account

Ask what niche they are in, which keywords to watch, which profiles they want to engage with, and their actual X handle.

update_account(
  account="main",
  target_keywords=["..."],
  competitor_profiles=["https://x.com/..."],
  self_handles=["theirhandle"],
)

self_handles matters more than it looks. Without it the own-post guard cannot fire, and nothing can later find the posts this account published, because approve_draft returns no URL.

7. Set the persona

Ask how they want to sound. The repo ships three starting points under presets/personas/ (builder, founder, curator), so offer them or write one together. Cover voice, topics, reply style, what to avoid, and one or two example replies. Under 4000 characters, markdown.

update_account(account="main", persona="...")

Batch the config edits where you can. Every update_account closes the warm browser session, so the next action pays a cold start.

8. Optional, only if it applies

• More accounts: repeat from step 5. If they want separate network routes, add_proxy(pool, proxy_url) then update_account(account, proxy="pool:<name>").
• An LLM key: interactive use needs none. You are the writer, and the server drives the browser. A key is only needed for unattended background automation and "auto" text, set under llm in config/settings.json.

9. Prove it works

Stage one real but harmless draft, a reply or a post, and show it with list_drafts.

Then tell the user plainly: write tools return a draft and change nothing on X. Only approve_draft(draft_id) publishes. That gate is on by default and it is the reason this is safe to hand to an agent.

When something fails

Run x-use doctor, read the actual error, fix that cause, and only then continue. Every tool returns {"ok": true, ...} or {"ok": false, "error": {"type", "message"}}. On an error envelope, explain it and stop rather than retrying in a loop.

After setup

The installed skills take over: x-use-engage for research and replies, x-use-content for original posts, x-use-review for the daily digest, and x-use for tool routing and conventions.

Clients without skill support get the same workflows as MCP prompts (research_niche, draft_replies, review_and_publish, daily_check, setup_account), plus read-only resources (xuse://accounts, xuse://accounts/{account_id}/persona, xuse://drafts/pending) for context worth attaching rather than fetching.

Full tool reference: docs/MCP_GUIDE.md.

x-use

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

x-use drives a real, stealth-hardened browser instead of the paid X API. It posts, replies, searches, and engages across as many accounts as you configure, writes content with your own LLM, and exposes everything as MCP tools, so Claude Desktop, Claude Code, Cursor, and other MCP clients can run your X presence directly.

The X API's pricing tiers put write access out of reach for exactly the people who want to automate a couple of accounts. x-use sidesteps the API entirely: if a logged-in browser can do it, an MCP client can ask for it. And because write actions go through a draft-approval step by default, an agent can prepare work all day while nothing reaches X until a human says yes.

x-use is the v2 relaunch of twitter-automation-ai. The repository was renamed; old URLs keep redirecting, and stars, forks, and issues came along intact.

Install

From PyPI (CLI and MCP server):

pip install x-use-mcp

For the full repo setup (presets, example configs, docs), the one-line installer clones the repo, installs x-use into its own virtual environment, and finishes with x-use doctor so you can see what is left to configure.

Windows (PowerShell):

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

macOS / Linux / Git Bash:

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

Or the manual way:

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

Requires Python 3.10+ and Chrome. Any of these gives you the x-use command.

Automatic setup

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

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"]
    }
  }
}

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. Write tools return a reviewable draft and change nothing until you call approve_draft with the returned draft_id. Opt out with "mcp": { "draft_mode": false } in config/settings.json.

MCP tools

33 tools in six groups, full reference with signatures and examples: docs/MCP_GUIDE.md. Two safety gates: write tools run in draft mode by default (review, then approve_draft), and the queue only stores work until an explicit process_queue call.

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.

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.

Agent skills

x-use init (or x-use skills install) installs five agent skills for Claude Code and Codex: x-use (overview), x-use-setup (zero-knowledge onboarding interview), x-use-engage (research + reply workflow), x-use-content (content creation), x-use-review (daily digest). Claude Code users can also install from the marketplace: /plugin marketplace add ihuzaifashoukat/x-use.

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 still works via a deprecation shim. It is scheduled for removal in v3.0; the whole v2 series keeps it.

Features

x-u