X MCP Server

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

Este proyecto permite a los agentes compatibles con MCP, incluidos los agentes de ChatGPT, leer de forma segura desde y publicar en cuentas de X mediante un servidor local que se ejecuta en tu propio ordenador.

El servidor admite:

• Leer la cuenta de X autenticada.

• Buscar usuarios de X por nombre de usuario.

• Leer publicaciones por ID.

• Listar publicaciones recientes de un usuario.

• Buscar publicaciones recientes con la sintaxis de búsqueda de X.

• Crear publicaciones y respuestas cuando el modo de escritura está habilitado explícitamente.

• Seleccionar una cuenta de X diferente por instalación local del ordenador.

• Ejecutarse a través de stdio para hosts MCP locales.

• Ejecutarse a través de HTTP Streamable local para ChatGPT mediante OpenAI Secure MCP Tunnels.

Estado del Proyecto

Este es un MVP funcional.

Implementado:

• Servidor MCP sobre stdio.

• Servidor MCP sobre Streamable HTTP.

• Cliente oficial de la API de X.

• Configuración local de múltiples cuentas.

• Modo seguro read-only por defecto.

• Modo read-write explícito para publicar y responder.

• Asistente local de OAuth 2.0 Authorization Code + PKCE para la reautorización de cuentas de X.

• Pruebas unitarias con Vitest.

• Guía de conexión de ChatGPT a través de OpenAI Secure MCP Tunnels.

• Guía del ciclo de vida del servidor local para el inicio manual y automático en Windows.

Related MCP server: X API FastMCP Server

Cómo Funciona

Para hosts MCP locales:

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

Para agentes de ChatGPT:

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

Las credenciales de X permanecen locales. ChatGPT se conecta al servidor MCP local a través del túnel; no recibe tus tokens de acceso de X.

Herramientas MCP Disponibles

Las herramientas de escritura están bloqueadas a menos que se establezca X_MCP_MODE=read-write.

Requisitos

• Node.js 20 o superior.

• Una cuenta de X Developer.

• Una aplicación X Developer con OAuth 2.0 habilitado.

• Ámbitos de lectura de X: tweet.read users.read.

• Ámbito de escritura de X para publicar y responder: tweet.write.

• Ámbito de actualización recomendado de X: offline.access.

• Para ChatGPT: modo desarrollador habilitado.

• Para conexiones locales de ChatGPT: un OpenAI Secure MCP Tunnel y tunnel-client.

Instalación Paso a Paso

1. Clonar el Repositorio

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

Si ya tienes el repositorio:

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

2. Instalar Dependencias

npm install

3. Crear un Archivo de Entorno Local

Copy-Item .env.example .env

Edita .env localmente.

No hagas commit de .env. Puede contener tokens de acceso, tokens de actualización, secretos de cliente y claves API privadas.

4. Configurar la Cuenta de X Activa

Para una cuenta local con nombre:

X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only
X_API_BASE_URL=https://api.x.com

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

Para múltiples cuentas en el mismo ordenador:

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=

X_MCP_ACCOUNT selecciona el perfil local utilizado por esta instalación. Diferentes ordenadores pueden seleccionar diferentes cuentas sin cambiar código.

El modo heredado de cuenta única también es compatible:

X_MCP_ACCOUNT=default
X_USER_ACCESS_TOKEN=

Las instalaciones nuevas deberían preferir cuentas con nombre.

5. Elegir el Transporte

Para hosts MCP locales que inician el proceso directamente:

X_MCP_TRANSPORT=stdio

Para ChatGPT a través de un túnel local:

X_MCP_TRANSPORT=http
X_MCP_HTTP_PORT=3001
X_MCP_HTTP_PATH=/mcp

6. Ejecutar Comprobaciones de Tipos y Pruebas

npm run typecheck
npm test
npm run build

7. Iniciar el Servidor MCP

Para stdio:

npm run dev

Para HTTP local:

npm run dev:http

El endpoint HTTP MCP predeterminado es:

http://127.0.0.1:3001/mcp

Comprobación de salud:

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

Respuesta esperada:

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

Ciclo de Vida del Servidor MCP Local

Cuando ChatGPT usa este MCP a través de un túnel, deben estar ejecutándose dos procesos locales:

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

Si alguno de los procesos se detiene, ChatGPT no puede usar las herramientas MCP.

Iniciar Manualmente

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

Mantén ambas terminales abiertas.

Verificar Disponibilidad Local

Comprueba el servidor MCP:

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

Comprueba el cliente de túnel:

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

El endpoint de disponibilidad del túnel debería devolver HTTP 200.

Detener Manualmente

Pulsa Ctrl+C en:

• La terminal que ejecuta npm run dev:http.

• La terminal que ejecuta tunnel-client run.

Una vez detenidos ambos, ChatGPT ya no tiene acceso al servidor MCP local.

Cambiar Cuenta o Modo de Seguridad

Edita .env.

Cambiar cuenta activa:

X_MCP_ACCOUNT=fcbnews2026

Habilitar modo de escritura:

X_MCP_MODE=read-write

Volver al modo seguro de solo lectura:

X_MCP_MODE=read-only

Reinicia el servidor HTTP MCP después de cambiar .env:

Ctrl+C
npm run dev:http

El túnel puede permanecer en ejecución si el puerto local y la ruta MCP no cambiaron.

Iniciar Automáticamente al Iniciar Sesión en Windows

Para un ordenador que deba alojar este MCP regularmente, usa el Programador de tareas de Windows.

Crea un script de inicio local, por ejemplo:

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

Registra la tarea programada:

$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."

Deshabilitar el inicio automático:

Disable-ScheduledTask -TaskName "X MCP FCBNews2026"

Habilitarlo de nuevo:

Enable-ScheduledTask -TaskName "X MCP FCBNews2026"

Eliminarlo:

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

Guía completa del ciclo de vida:

docs/local-server-lifecycle.md

Conectar a ChatGPT

Flujo de alto nivel:

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.

Configuración MCP personalizada recomendada para ChatGPT:

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

Usa No authentication cuando el servidor MCP gestione las credenciales finales del servicio localmente, por ejemplo a través de .env.

Guía completa de configuración de ChatGPT:

docs/chatgpt-mcp-setup.md

Reautorizar una Cuenta de X

En X Developer, configura la aplicación:

OAuth 2.0: Enabled
App permissions: Read and write
Callback URI: http://127.0.0.1:3002/callback
Website URL: http://127.0.0.1:3002

Ejecuta:

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

Abre la URL generada mientras tengas la sesión iniciada en la cuenta de X deseada. Después de la autorización, el asistente actualiza .env con el token de la cuenta seleccionada.

Reinicia el servidor MCP después de la reautorización:

npm run dev:http

Luego verifica con:

x_get_active_account

Guía detallada de OAuth:

docs/x-oauth.md

Modelo de Seguridad

El servidor se inicia en modo de solo lectura por defecto:

X_MCP_MODE=read-only

Las herramientas de escritura requieren:

X_MCP_MODE=read-write

Antes de publicar:

• Verifica la cuenta activa con x_get_active_account.

• Confirma el texto exacto a publicar.

• Asegúrate de que el token de X tenga tweet.write.

• Pide al agente que devuelva el post_id generado.

• No consideres una publicación como publicada hasta que X devuelva un ID.

Scripts

Documentación

• docs/project-architecture.md: arquitectura del proyecto.

• docs/configuration.md: variables de entorno y configuración de múltiples cuentas.

• docs/local-server-lifecycle.md: iniciar, detener y automatizar el servidor MCP local.

• docs/tools.md: herramientas MCP y contratos de uso.

• docs/x-oauth.md: reautorización OAuth de X.

• docs/development.md: pautas de desarrollo, pruebas y cambios.

• docs/chatgpt-mcp-setup.md: configuración paso a paso de ChatGPT MCP.

Seguridad Operativa

• Mantén las credenciales fuera de Git.

• Mantén read-only como modo predeterminado.

• Habilita read-write solo para flujos de trabajo controlados.

• Verifica la cuenta activa antes de publicar.

• No registres tokens de acceso ni tokens de actualización.

• No pegues tokens en chats, issues, documentos ni pull requests.

• No ejecutes el inicio automático en modo read-write en ordenadores compartidos.

Licencia

Aún no se ha seleccionado una licencia de código abierto.