x-client-mcp

MCP server for X/Twitter HTTP API operations -- posting, engagement, account warming, and timeline reading. Uses cookie-based auth from harvested browser sessions.

Features

• Post tweets and threads from any vault account
• Engagement actions -- like, reply, follow
• Media uploads (image/video)
• Timeline and notification reading
• Account warming scheduler with graduated daily action limits (browse -> like -> follow -> reply -> post)
• Account import for externally-created accounts with known cookies
• Shared vault with x-browser-mcp for seamless browser-to-API handoff
• Built on agent-twitter-client for HTTP API calls

Install

npm install x-client-mcp

Requires Node.js >= 18.

Usage

As an MCP server (stdio)

npx x-client-mcp

In MCP client config

{
  "mcpServers": {
    "x-client": {
      "command": "npx",
      "args": ["x-client-mcp"],
      "env": {
        "X_VAULT_PASSPHRASE": "...",
        "X_VAULT_PATH": "~/.claude-workflow/x-accounts.json"
      }
    }
  }
}

Tools

Posting

| Tool | Description | |------|-------------| | x_post_tweet | Post a tweet (max 280 chars). Optionally reply to a tweet via reply_to ID. Requires account in warming (day 8+) or active state. | | x_post_thread | Post a thread (array of tweet texts) as chained replies. | | x_reply_tweet | Reply to a specific tweet by ID. |

Engagement

| Tool | Description | |------|-------------| | x_like_tweet | Like a tweet by ID. | | x_follow_user | Follow a user by handle. |

Media

| Tool | Description | |------|-------------| | x_upload_media | Upload an image or video file. Returns a media_id for use in tweets. |

Reading

| Tool | Description | |------|-------------| | x_get_timeline | Read the home timeline. Returns tweet text, author, engagement counts. count defaults to 20. | | x_get_notifications | Search for tweets mentioning the account handle (uses search, not notifications API -- only @mentions, not likes/follows/retweets). count defaults to 20. |

Warming

| Tool | Description | |------|-------------| | x_warming_step | Execute one warming action based on the account's day in the warming schedule. Automatically graduates from passive actions (browse, like) to active ones (reply, post). |

Account Management

| Tool | Description | |------|-------------| | x_list_accounts | List all accounts with state, warming progress, and cookie status. Optionally filter by state. | | x_import_account | Import an existing account with known auth_token and ct0 cookies. Default state is active. |

Tool Reference

x_post_tweet

Post a tweet from a specific account. Optionally reply to another tweet.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | text | string | yes | Tweet text (max 280 chars) | | reply_to | string | no | Tweet ID to reply to |

x_post_thread

Post a thread (multiple tweets) as chained replies.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | tweets | string[] | yes | Array of tweet texts for the thread |

x_reply_tweet

Reply to a specific tweet.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | tweet_id | string | yes | Tweet ID to reply to | | text | string | yes | Reply text |

x_like_tweet

Like a tweet by ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | tweet_id | string | yes | Tweet ID to like |

x_follow_user

Follow a user by handle.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | username | string | yes | Username (handle) to follow |

x_upload_media

Upload media (image/video) for use in tweets.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | file_path | string | yes | Path to the media file | | media_type | string | yes | MIME type (e.g. image/jpeg, video/mp4) |

x_get_timeline

Read the home timeline for a specific account.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | count | number | no | Number of tweets to fetch (default: 20) |

x_get_notifications

Search for tweets mentioning the account handle. Uses tweet search (@handle), not the notifications API -- only returns @mentions, not likes/follows/retweets.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault | | count | number | no | Number of results to fetch (default: 20) |

x_warming_step

Execute one warming action for an account based on its day in the warming schedule. Automatically graduates from passive actions (browse, like) to active ones (reply, post).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account_id | string | yes | Account ID in the vault |

x_list_accounts

List all accounts in the vault with their current state and warming progress. Returns a summary (no sensitive data).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | state | string | no | Filter by account state |

x_import_account

Import an existing X account into the vault with known cookies. Useful for accounts created manually or whose cookies were harvested externally.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | handle | string | yes | X handle (without @) | | auth_token | string | yes | auth_token cookie value | | ct0 | string | yes | ct0 cookie value (CSRF token) | | user_id | string | no | X user ID (from twid cookie). Used as account ID if provided. | | state | string | no | Initial account state: warming, active, or profile_setup (default: active) | | email | string | no | Email used for the account | | password | string | no | Account password |

Configuration

| Variable | Description | Default | |----------|-------------|---------| | X_VAULT_PASSPHRASE | Encryption passphrase for the account vault | - | | X_VAULT_PATH | Path to vault file | ~/.claude-workflow/x-accounts.json |

This server has minimal config because it operates entirely via HTTP using cookies already stored in the vault. Accounts and cookies are created by x-browser-mcp or imported with x_import_account.

Warming Schedule

New accounts go through a graduated warming period to avoid triggering X's anti-spam systems:

| Day | Max Actions | Allowed | |-----|-------------|---------| | 0-2 | Low | Browse, like | | 3-5 | Medium | Browse, like, follow | | 6-7 | Medium | Browse, like, follow, reply | | 8+ | Full | Browse, like, follow, reply, post |

Once warming completes, the account state transitions from warming to active.

Account State Machine

Shared with x-browser-mcp:

created -> email_verified -> phone_verified -> profile_setup -> warming -> active
                                                                           |
                                                                    suspended / locked

x_import_account can place accounts directly into warming, active, or profile_setup state.

License

MIT