safe-twitter-mcp

An X (Twitter) MCP server with cost guardrails, approve-before-post safety, and a local spend log.

Why

Since 2026 the X API is pay-per-use: every post read, user lookup and post created is billed individually. An agent that runs a broad search, retries in a loop or posts a link without noticing can turn a few minutes of work into a real bill, or publish something nobody approved.

This server gives an MCP client a small, deliberate set of X tools and puts a guard in front of every API call. It checks daily budgets before spending anything, logs the estimated cost of each call, and never publishes without a dry run followed by an explicit confirmation.

It works with any MCP client, such as Claude Desktop or Claude Code.

Related MCP server: x-mcp

Features

• Dry run, then confirm. Posting, threads and deletes return a preview first: final text, X-weighted character count, estimated cost and today's totals. Nothing is published until the tool is called again with confirm: true.

• Daily caps. Separate limits for posts read, posts created and estimated spend, counted in your own timezone. Calls that would cross a limit are refused up front with the remaining allowance and the config key to change.

• Link-cost warning. A post containing a URL costs about 13 times more. The preview flags it and suggests putting the link in a reply instead.

• Duplicate detection. Refuses an exact repeat of anything posted in the last 7 days.

• Per-call cost log. Every API call is appended to data/usage.jsonl with its endpoint, units and estimated cost; get_usage_summary reports today, 7 days or 30 days.

• Human-readable errors. 401, 402, 403 and 429 responses are translated into the specific fix (regenerate the token, add credits, wait until the reset time) with no stack traces and no secrets.

• Config without restarts. config.json is read on every call, so budget and watch-list changes apply immediately.

Tools

Dry runs (confirm: false) of create_post and create_thread are free; the delete_post dry run fetches the post first. Tools that act on the authenticated account look up its id once ($0.01) and cache it.

Architecture

flowchart LR
    A["MCP client<br/>(Claude Desktop / Claude Code)"] -- stdio --> B["MCP server<br/>tools + zod schemas"]
    B --> C["Guard<br/>budget check + usage log"]
    C --> D["twitter-api-v2<br/>OAuth 1.0a"]
    D --> E["X API v2"]
    C -.-> F[("data/usage.jsonl")]
    B -.-> G[("config.json")]

Every X call goes through one wrapper, guarded() in src/x/client.ts. It checks the planned worst case against today's budgets, makes the call, records the actual units and estimated cost, and converts any error into an actionable message. stdout is reserved for the MCP protocol, so all logging goes to stderr.

src/
  index.ts          server setup and tool registration
  config.ts         config.json loading and validation
  env.ts            .env loading and validation
  paths.ts          paths resolved relative to the build, not the working directory
  guard/            budgets, draft review, usage log and cost table
  tools/            one file per tool
  x/                API client wrapper, formatting, character counting, user cache
tests/              unit tests (no network, no keys)
scripts/smoke.ts    manual end-to-end check against the live API

Quick start

Prerequisites

• Node.js 22.12 or later

• An X developer account with pay-per-use credits (see X developer setup)

• An MCP client such as Claude Desktop or Claude Code

Install and build

git clone https://github.com/saadatdev/safe-twitter-mcp.git
cd safe-twitter-mcp
npm install
cp .env.example .env                  # then fill in the four X keys
cp config.example.json config.json    # then set your timezone, topics and watch list
npm run build

On Windows PowerShell, use Copy-Item in place of cp.

Smoke test

npm run smoke

This verifies the credentials (GET /2/users/me) and runs one 10-result search. It costs about $0.06 and never posts.

Connect to Claude Desktop

Open the config file (Claude Desktop → Settings → Developer → Edit Config):

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server under mcpServers, using the absolute path to dist/index.js. Windows paths need escaped backslashes:

{
  "mcpServers": {
    "safe-twitter": {
      "command": "node",
      "args": ["C:\\path\\to\\safe-twitter-mcp\\dist\\index.js"]
    }
  }
}

On macOS:

{
  "mcpServers": {
    "safe-twitter": {
      "command": "node",
      "args": ["/Users/you/path/to/safe-twitter-mcp/dist/index.js"]
    }
  }
}

Quit Claude Desktop completely and reopen it, then ask it to show your X usage summary. Credentials are read from the .env file next to the server, so they never go in the client config.

Connect to Claude Code

claude mcp add --scope user safe-twitter -- node /absolute/path/to/safe-twitter-mcp/dist/index.js

X developer setup

1. In console.x.com, create a project and an app.

2. Under User authentication settings, set App permissions to Read and write.

3. Regenerate the Access Token and Secret after changing permissions. A token created before the change stays read-only, and every post fails with 403. This is the most common setup problem; the server's 403 message points to it.

4. Copy the API Key, API Key Secret, Access Token and Access Token Secret into .env.

5. Add credits under Billing. With a zero balance every call fails with 402, which the server reports as an empty credit balance.

Configuration reference

config.json (copied from config.example.json) is read on every call.

Costs

The usage log prices calls with this table, from src/guard/usage.ts (as listed on 10 Oct 2026):

Worked example. One digest a day over 5 accounts (25 posts) plus a 10-post topic search ($0.175), two 10-result searches ($0.10), three posts ($0.045), 20 mentions ($0.02) and 10 own posts for stats ($0.01) comes to about $0.35 a day, or roughly $10.50 a month. Posting one of those three with a link adds about $5.50 a month.

X changes its prices. The usage page in console.x.com is the source of truth; the local log is an estimate. See docs/x-api-reference.md for endpoints and sources.

Safety and X rules

Deliberately not implemented:

• Likes, follows, reposts and quote posts. Likes and follows were removed from self-serve plans in April 2026, and automated engagement is what gets accounts restricted.

• Automatic replies to search results. X only allows API replies in "summoned" contexts, where the account was mentioned or quoted. Replies happen only through create_post with an explicit reply_to_id and confirmation.

• Scraping, browser automation and unofficial endpoints. Prohibited on every X tier.

• No unattended scheduling: every post is a deliberate, approved action.

Secrets are loaded only from .env, never logged and never included in tool results or errors.

Development

npm run dev      # run from source with tsx
npm test         # unit tests: cost math, budgets, character counting, URL detection, timezones
npm run build    # type-check and compile to dist/

Tests need no API keys and no network.

Roadmap

• Scheduling queue with randomized timing and the same approve-before-post flow

• Remote hosting over Streamable HTTP for use from multiple devices

License

MIT © 2026 Saadat Baig

Disclaimer

This project is not affiliated with, endorsed by or sponsored by X Corp. "X" and "Twitter" are trademarks of X Corp. Use of the X API is subject to X's Developer Agreement and policies.