X MCP Server

TypeScript Model Context Protocol (MCP) server for the official X API.

This project lets MCP-compatible agents, including ChatGPT agents, safely read from and publish to X accounts through a local server that runs on your own computer.

The server supports:

• Reading the authenticated X account.

• Looking up X users by username.

• Reading posts by ID.

• Listing recent posts from a user.

• Searching recent posts with X search syntax.

• Creating posts and replies when write mode is explicitly enabled.

• Selecting a different X account per local computer installation.

• Running over stdio for local MCP hosts.

• Running over local Streamable HTTP for ChatGPT through OpenAI Secure MCP Tunnels.

Project Status

This is a functional MVP.

Implemented:

• MCP server over stdio.

• MCP server over Streamable HTTP.

• Official X API client.

• Local multi-account configuration.

• Recommended xurl authentication provider, using X's official CLI for OAuth token storage, refresh and rotation.

• Safe read-only mode by default.

• Explicit read-write mode for publishing and replies.

• Legacy local OAuth 2.0 Authorization Code + PKCE helper for direct env-token setups.

• Unit tests with Vitest.

• ChatGPT connection guide through OpenAI Secure MCP Tunnels.

• Local server lifecycle guide for manual and automatic startup on Windows.

Related MCP server: X API FastMCP Server

How It Works

For local MCP hosts:

MCP host
  -> stdio
  -> x-mcp-server
  -> official X API

For ChatGPT agents:

ChatGPT agent
  -> custom MCP app
  -> OpenAI Secure MCP Tunnel
  -> tunnel-client on your computer
  -> http://127.0.0.1:3001/mcp
  -> x-mcp-server
  -> official X API

The X credentials stay local. ChatGPT connects to the local MCP server through the tunnel; it does not receive your X access tokens.

Available MCP Tools

Write tools are blocked unless X_MCP_MODE=read-write is set.

Requirements

• Node.js 20 or newer.

• An X Developer account.

• An X Developer App with OAuth 2.0 enabled.

• X read scopes: tweet.read users.read.

• X write scope for publishing and replies: tweet.write.

• Recommended X token manager: X's official xurl CLI.

• For ChatGPT: Developer Mode enabled.

• For ChatGPT local connections: an OpenAI Secure MCP Tunnel and tunnel-client.

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/lluisfont/x-mcp-server.git
cd x-mcp-server

If you already have the repository:

cd C:\Repos\x-mcp-server
git pull

2. Install Dependencies

npm install

3. Create a Local Environment File

Copy-Item .env.example .env

Edit .env locally.

Do not commit .env. It may contain local app names, usernames, access tokens, refresh tokens, client secrets, and private API keys.

4. Configure the Active X Account

Recommended setup: use xurl as the token manager.

X_AUTH_PROVIDER=xurl
X_XURL_APP=fcbnews
X_XURL_USERNAME=FCBNews2026
X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only
X_API_BASE_URL=https://api.x.com

Configure xurl once outside this project:

$secret = Read-Host "X OAuth Client Secret" -AsSecureString
$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret)
)
npx -y @xdevplatform/xurl auth apps add fcbnews --client-id "<OAuth 2.0 Client ID>" --client-secret $plain --redirect-uri http://localhost:8080/callback
npx -y @xdevplatform/xurl auth oauth2 --app fcbnews FCBNews2026

Register this callback URI in the X Developer App:

http://localhost:8080/callback

xurl stores tokens in its own local store and refreshes/persists them when needed. The MCP server calls:

npx -y @xdevplatform/xurl token --app fcbnews -u FCBNews2026

Legacy direct-token setup is still available with X_AUTH_PROVIDER=env:

X_AUTH_PROVIDER=env
X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

X_ACCOUNT_LLUISFONT_USER_ACCESS_TOKEN=
X_ACCOUNT_LLUISFONT_REFRESH_TOKEN=

The legacy single-account env-token mode is also supported:

X_AUTH_PROVIDER=env
X_MCP_ACCOUNT=default
X_USER_ACCESS_TOKEN=

New installations should prefer X_AUTH_PROVIDER=xurl.

5. Choose the Transport

For local MCP hosts that start the process directly:

X_MCP_TRANSPORT=stdio

For ChatGPT through a local tunnel:

X_MCP_TRANSPORT=http
X_MCP_HTTP_PORT=3001
X_MCP_HTTP_PATH=/mcp

6. Run Type Checks and Tests

npm run typecheck
npm test
npm run build

7. Start the MCP Server

For stdio:

npm run dev

For local HTTP:

npm run dev:http

The default HTTP MCP endpoint is:

http://127.0.0.1:3001/mcp

Health check:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Expected response:

{"ok":true,"transport":"http","activeAccount":"fcbnews2026","mode":"read-only"}

Local MCP Server Lifecycle

When ChatGPT uses this MCP through a tunnel, two local processes must be running:

1. The MCP HTTP server
   -> npm run dev:http
   -> http://127.0.0.1:3001/mcp

2. tunnel-client
   -> .\.tools\tunnel-client\tunnel-client.exe run --profile <profile>
   -> OpenAI Secure MCP Tunnel

If either process is stopped, ChatGPT cannot use the MCP tools.

Start Manually

Terminal 1:

cd C:\Repos\x-mcp-server
npm run dev:http

Terminal 2:

cd C:\Repos\x-mcp-server
.\.tools\tunnel-client\tunnel-client.exe run --profile x-fcbnews

Keep both terminals open.

Verify Local Availability

Check the MCP server:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Check the tunnel client:

Invoke-WebRequest http://127.0.0.1:8080/readyz -UseBasicParsing

The tunnel readiness endpoint should return HTTP 200.

Stop Manually

Press Ctrl+C in:

• The terminal running npm run dev:http.

• The terminal running tunnel-client run.

Once both are stopped, ChatGPT no longer has access to the local MCP server.

Change Account or Safety Mode

Edit .env.

Change active account:

X_MCP_ACCOUNT=fcbnews2026

Enable write mode:

X_MCP_MODE=read-write

Return to safe read-only mode:

X_MCP_MODE=read-only

Restart the MCP HTTP server after changing .env:

Ctrl+C
npm run dev:http

The tunnel can remain running if the local port and MCP path did not change.

Start Automatically on Windows Login

For a computer that should regularly host this MCP, use Windows Task Scheduler.

Create a local startup script, for example:

C:\Users\<user>\mcp-start\x-fcbnews-start.ps1

Script:

$repo = "C:\Repos\x-mcp-server"
$profile = "x-fcbnews"

Set-Location $repo

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; npm run dev:http"
) -WindowStyle Minimized

Start-Sleep -Seconds 5

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; .\.tools\tunnel-client\tunnel-client.exe run --profile $profile"
) -WindowStyle Minimized

Register the scheduled task:

$action = New-ScheduledTaskAction `
  -Execute "powershell.exe" `
  -Argument "-ExecutionPolicy Bypass -File `"C:\Users\<user>\mcp-start\x-fcbnews-start.ps1`""

$trigger = New-ScheduledTaskTrigger -AtLogOn

Register-ScheduledTask `
  -TaskName "X MCP FCBNews2026" `
  -Action $action `
  -Trigger $trigger `
  -Description "Starts the local X MCP server and OpenAI tunnel-client at Windows logon."

Disable automatic startup:

Disable-ScheduledTask -TaskName "X MCP FCBNews2026"

Enable it again:

Enable-ScheduledTask -TaskName "X MCP FCBNews2026"

Delete it:

Unregister-ScheduledTask -TaskName "X MCP FCBNews2026" -Confirm:$false

Full lifecycle guide:

docs/local-server-lifecycle.md

Connect to ChatGPT

High-level flow:

1. Run the MCP server over local HTTP.
2. Create a tunnel in OpenAI Platform.
3. Create a local tunnel-client profile pointing to http://127.0.0.1:3001/mcp.
4. Start tunnel-client.
5. Create a custom MCP app in the ChatGPT agent using Connection: Tunnel.
6. Test x_get_active_account or x_get_me before any write operation.

Recommended ChatGPT custom MCP settings:

Connection: Tunnel
Tunnel: <your OpenAI tunnel>
Authentication: No authentication

Use No authentication when the MCP server manages the final service credentials locally, for example through .env.

Full ChatGPT setup guide:

docs/chatgpt-mcp-setup.md

Reauthorize an X Account

Recommended xurl flow:

npx -y @xdevplatform/xurl auth oauth2 --app fcbnews FCBNews2026

Use the legacy helper only for X_AUTH_PROVIDER=env:

$env:X_OAUTH_CLIENT_ID = "<OAuth 2.0 Client ID>"
$env:X_MCP_ACCOUNT = "fcbnews2026"
npm run x:oauth

Restart the MCP server after reauthorization:

npm run dev:http

Then verify with:

x_get_active_account

Detailed OAuth guide:

docs/x-oauth.md

Safety Model

The server starts in read-only mode by default:

X_MCP_MODE=read-only

Write tools require:

X_MCP_MODE=read-write

Before publishing:

• Verify the active account with x_get_active_account.

• Confirm the exact text to publish.

• Ensure the X token has tweet.write.

• Prefer X_AUTH_PROVIDER=xurl so X token refresh and rotation are handled by X's official CLI.

• Ask the agent to return the generated post_id.

• Do not treat a post as published until X returns an ID.

Scripts

Documentation

• docs/project-architecture.md: project architecture.

• docs/configuration.md: environment variables and multi-account setup.

• docs/local-server-lifecycle.md: start, stop, and automate the local MCP server.

• docs/tools.md: MCP tools and usage contracts.

• docs/x-oauth.md: X OAuth reauthorization.

• docs/development.md: development, testing, and change guidelines.

• docs/chatgpt-mcp-setup.md: step-by-step ChatGPT MCP setup.

Operational Security

• Keep credentials outside Git.

• Keep read-only as the default mode.

• Enable read-write only for controlled workflows.

• Verify the active account before publishing.

• Do not log access tokens or refresh tokens.

• Do not paste tokens into chats, issues, docs, or pull requests.

• Do not run automatic startup in read-write mode on shared computers.

License

No open-source license has been selected yet.