Log inSubmit server
X MCP AI logo

X MCP AI

Policy-gated MCP access to X API v2 for reading, searching, posting, engagement, lists, media, social graphs, and DMs.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install X MCP AI

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "x-mcp-ai": {
      "command": "npx",
      "args": [
        "-y",
        "x-mcp-ai@0.8.0"
      ],
      "env": {
        "X_MCP_AUTH_MODE": "YOUR_VALUE_HERE",
        "X_MCP_CLIENT_ID": "YOUR_VALUE_HERE",
        "X_MCP_CLIENT_SECRET": "YOUR_VALUE_HERE",
        "X_MCP_BEARER_TOKEN": "YOUR_VALUE_HERE",
        "X_MCP_TOKEN_FILE": "YOUR_VALUE_HERE",
        "X_MCP_POLICY": "YOUR_VALUE_HERE",
        "X_MCP_CREDIT_BUDGET": "YOUR_VALUE_HERE",
        "X_MCP_BUDGET_MODE": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

x-mcp-ai MCP server exposes X (Twitter) API v2 through 41 typed MCP tools across 12 packages. It supports OAuth 2.0 PKCE and app-only bearer authentication, with policy presets controlling read, engagement, publishing, and management operations. Every result includes usage cost data, and an optional hard credit budget can reject calls that exceed the configured cap. Reach for it when an MCP client needs controlled access to X data or account actions.

Use cases

  • Search recent X posts from an MCP client
  • Read X timelines and user information
  • Publish posts under an explicit policy
  • Set likes and manage supported engagement actions
  • Enforce a session spending limit for X API calls

Key features

  • 41 typed tools across 12 packages
  • Policy presets with explicit allow and deny cells
  • OAuth 2.0 PKCE and app-only bearer authentication
  • Per-call costs and configurable credit budgets
  • Structured JSON-Schema tool outputs
  • Cursor pagination and rate-limit tracking

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

6/6 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 16d ago via OSV.dev · x-mcp-ai@0.8.0 (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1Stargazers on the source repository.
npm downloads162Package downloads in the last 30 days.
Last commit20d agoMost recent push to the default branch.

How X MCP AI works

What x-mcp-ai does

The x-mcp-ai MCP server connects MCP-compatible agents to the X API v2. Its 41 typed tools cover reading posts, users, and timelines; recent and full-archive search; engagement actions; post publishing; list management; media uploads; social-graph queries; and direct-message reading and sending when explicitly enabled.

The tool surface is organized across 12 packages. Examples include x_search_recent for recent search, x_like_set for changing a like, and x_post_create for publishing a post. Tools return structured content alongside a text representation, and each tool advertises a JSON Schema output definition.

How it works

The x-mcp-ai MCP server uses a two-axis policy model based on operation:domain cells. Presets include read-only, engage, publish, manage, and full; the default is read-only. Writes require an enabled policy cell, and explicit denies override both allows and presets. Direct-message read and write cells are excluded from every preset, including full, so they require separate opt-in.

OAuth 2.0 PKCE is the primary user-context mode. Refresh tokens rotate automatically, and token storage can use a file or supported operating-system keychain. App-only bearer authentication is available for read-only deployments without user context.

Calls report their individual cost and the running session total. Configure a USD credit budget to warn or refuse calls that would exceed the limit. The server also tracks endpoint rate limits, handles cursor pagination, applies availability classes, and returns typed failures that identify retryability and whether an agent or operator should fix the problem.

Setup and configuration

Node.js 22 or newer is required. The published package can be launched with a pinned npm version through npx, or the repository can be cloned, installed with npm ci, built, and started from the generated Node entry point. A doctor command performs a sanity check without making billable API calls.

Configure the server through environment variables; it does not prompt interactively. OAuth setup requires an X developer app and OAuth 2.0 client ID, with a client secret for confidential clients. Run the authorize subcommand once to complete the PKCE flow and store tokens. App-only mode instead uses an X bearer token and exposes read endpoints only.

Useful controls include X_MCP_POLICY, X_MCP_POLICY_ALLOW, and X_MCP_POLICY_DENY for permissions; X_MCP_CREDIT_BUDGET and X_MCP_BUDGET_MODE for spend limits; and X_MCP_MEDIA_DIR to constrain upload paths. The API base URL must use HTTPS and the x.com host pattern unless the documented insecure override is enabled.

Tools and capabilities

The x-mcp-ai MCP server provides capabilities for:

  • Reading posts, users, timelines, and social-graph data.
  • Searching recent posts and the full archive.
  • Liking or otherwise managing supported engagement actions.
  • Creating posts and uploading media.
  • Managing lists.
  • Reading and sending direct messages after explicit permission is granted.
  • Returning compact, structured results with cost and session totals.

Limitations and notes

The project is pre-1.0 and its public API may change. X API requests are billed, and prepaid credits are required. App-only authentication cannot perform user-context operations. Media uploads are denied by default unless files resolve inside the configured media directory.

Security defaults include host-scoped authorization headers, no redirects for token-bearing requests, restrictive token-file creation, and marking returned text as untrusted content. Pin an exact package version while the project remains on the 0.x release line.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about X MCP AI

x-mcp-ai is an MCP server that connects AI agents to the X (Twitter) API v2 through 41 typed tools. It supports searching and reading posts, users, and timelines, plus publishing, engagement, lists, media, social-graph queries, and opt-in direct-message operations under policy controls.

Install it by configuring your MCP client to run `npx -y x-mcp-ai@0.8.0`. You can also clone the repository, run `npm ci`, build with `npm run build`, and start the generated Node entry point.

Set `X_MCP_CREDIT_BUDGET` to a USD amount and choose `X_MCP_BUDGET_MODE=hard` to reject calls that would exceed it. Results include the individual call cost and the running session total.

Yes, x-mcp-ai works with Cursor through its MCP configuration.

Yes, it can read and send direct messages when their policy cells are explicitly enabled. Direct-message permissions are not included in any preset, including `full`, so they require separate opt-in.

Related MCP servers

All in Social Media All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewX MCP AI AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/x-mcp-ai?style=directory)](https://allmcps.com/mcp/x-mcp-ai)
HTML Embed
<a href="https://allmcps.com/mcp/x-mcp-ai"><img src="https://allmcps.com/api/badge/x-mcp-ai?style=directory" alt="X MCP AI on AllMCPs" /></a>