X MCP Server

Un servidor MCP para la integración con X (Twitter), que permite leer cronologías e interactuar con tweets.

Documentación

X MCP Server

Un servidor de Model Context Protocol (MCP) para la integración con X (Twitter). Proporciona 26 herramientas para leer cronologías, publicar, buscar, interacción (me gusta, retweets, marcadores), búsqueda de usuarios, exportación de seguidores, menciones, me gusta, artículos y listas. Diseñado para usarse con Claude desktop y otros clientes compatibles con MCP.

Características

Cronología y búsqueda - Cronología de inicio, búsqueda de publicaciones recientes (ventana de 7 días)
Gestión de publicaciones - Crear, responder, citar y eliminar publicaciones con medios opcionales
Interacción - Me gusta/quitar me gusta, retweet/deshacer, marcar/desmarcar
Datos de usuario - Menciones, publicaciones con me gusta, seguidores, siguiendo, bloqueos, silenciados, listas propias, listas seguidas y membresías de listas
Búsqueda de usuarios - Obtener perfiles de usuario y sus publicaciones recientes
Carga de medios - Imágenes (PNG, JPEG, GIF, WEBP) y videos (MP4, MOV, AVI, WEBM, M4V) mediante la API de carga v2
Autenticación dual - OAuth 1.0a para operaciones de publicación, OAuth 2.0 para carga de medios (la carga v1.1 se retiró en junio de 2025)
Límite de velocidad - Seguimiento automático del límite de velocidad por endpoint con mensajes de error claros
TypeScript - Seguridad total de tipos, estructura de archivos modular

Requisitos previos

Node.js >= 18.0.0
Cuenta de desarrollador de X (Twitter)
Aplicación Claude desktop (o cualquier cliente compatible con MCP)

Acceso y precios de la X API

Nivel	Costo	Lecturas de publicaciones	Escrituras de publicaciones	Notas
Gratuito	$0	~100/mes	~500/mes	Sin me gusta/seguimientos; la carga de medios requiere OAuth 2.0
Básico	$200/mes	10,000/mes	3,000/mes	Búsqueda, acceso de lectura limitado
Pro	$5,000/mes	1,000,000/mes	300,000/mes	Búsqueda completa, stream filtrado
Pago por uso	Basado en créditos	~$0.005/lectura	Varía	Lanzado en febrero de 2026, límite de 2M de lecturas

Los endpoints de Me gusta y Seguir se eliminaron del nivel Gratuito en agosto de 2025. Los endpoints de Seguir/Bloquear son solo para Enterprise a partir de 2025.

Instalación

git clone https://github.com/DataWhisker/x-mcp-server.git
cd x-mcp-server
npm install
npm run build

Autenticación

El servidor admite dos métodos de autenticación. Necesitas al menos uno configurado.

OAuth 1.0a (Requerido para operaciones básicas)

Funciona para todas las operaciones de publicación/interacción/búsqueda/usuario.

Variable de entorno	Descripción
`TWITTER_API_KEY`	Consumer Key (API Key)
`TWITTER_API_SECRET`	Consumer Secret (API Key Secret)
`TWITTER_ACCESS_TOKEN`	User Access Token
`TWITTER_ACCESS_SECRET`	User Access Token Secret

Configuración: En el Portal de desarrolladores de X:

Crea un proyecto y una aplicación
Habilita OAuth 1.0a en "Configuración de autenticación de usuario"
Establece los permisos en "Lectura y escritura"
Genera claves de consumidor y tokens de acceso

OAuth 2.0 (Requerido para carga de medios)

El endpoint de carga de medios v1.1 se retiró en junio de 2025. La carga de medios ahora requiere OAuth 2.0 mediante la API de carga v2.

Opción A - Token de acceso directo:

Variable	Descripción
`TWITTER_OAUTH2_ACCESS_TOKEN`	Token de acceso de usuario OAuth 2.0 (expira en 2 horas)

Opción B - Renovación automática (recomendada para servidores de larga duración):

Variable	Descripción
`TWITTER_CLIENT_ID`	OAuth 2.0 Client ID
`TWITTER_CLIENT_SECRET`	Secreto de cliente OAuth 2.0 (opcional para clientes públicos)
`TWITTER_OAUTH2_REFRESH_TOKEN`	OAuth 2.0 Refresh Token

Los tokens se renuevan automáticamente y se guardan en ~/.x-mcp-tokens.json.

Configuración: En el Portal de desarrolladores de X:

En la configuración de tu aplicación, habilita OAuth 2.0
Establece el tipo en "Cliente confidencial" o "Cliente público"
Añade una URL de devolución de llamada
Solicita los alcances: tweet.read, tweet.write, users.read, media.write, offline.access, like.read, like.write, bookmark.read, bookmark.write, follows.read, block.read, mute.read, list.read

Configuración de Claude Desktop

Añade a %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["C:/path/to/x-mcp-server/build/index.js"],
      "env": {
        "TWITTER_API_KEY": "your-api-key",
        "TWITTER_API_SECRET": "your-api-secret",
        "TWITTER_ACCESS_TOKEN": "your-access-token",
        "TWITTER_ACCESS_SECRET": "your-access-secret",
        "TWITTER_OAUTH2_ACCESS_TOKEN": "your-oauth2-token"
      }
    }
  }
}

Backend de búsqueda Xquik opcional

search_tweets puede usar Xquik mientras el resto del servidor mantiene el cliente X API predeterminado. Configura:

Variable	Descripción
`X_MCP_SEARCH_BACKEND=xquik`	Enruta solo `search_tweets` a Xquik
`XQUIK_API_KEY`	Clave API de Xquik
`XQUIK_API_BASE_URL`	URL base opcional, por defecto `https://xquik.com/api/v1`

Herramientas disponibles (26)

Cronología y búsqueda

Herramienta	Descripción	Parámetros clave
`get_home_timeline`	Obtener publicaciones recientes de la cronología de inicio	`limit` (1-100)
`search_tweets`	Buscar publicaciones recientes (ventana de 7 días)	`query`, `limit`

Gestión de publicaciones

Herramienta	Descripción	Parámetros clave
`get_tweet`	Buscar una publicación por ID	`tweet_id`
`create_tweet`	Crear una publicación con medios opcionales	`text`, `image_path?`, `video_path?`
`reply_to_tweet`	Responder a una publicación con medios opcionales	`tweet_id`, `text`, `image_path?`, `video_path?`
`quote_tweet`	Citar una publicación con comentarios	`tweet_id`, `text`
`delete_tweet`	Eliminar tu publicación	`tweet_id`

Interacción

Herramienta	Descripción	Parámetros clave
`like_tweet`	Dar me gusta a una publicación (nivel Básico+)	`tweet_id`
`unlike_tweet`	Quitar un me gusta	`tweet_id`
`retweet`	Repostear en tu cronología	`tweet_id`
`undo_retweet`	Quitar un repost	`tweet_id`
`bookmark_tweet`	Marcar para más tarde	`tweet_id`
`unbookmark_tweet`	Quitar un marcador	`tweet_id`
`get_bookmarks`	Obtener tus marcadores	`limit` (1-100)

Usuarios

Herramienta	Descripción	Parámetros clave
`get_user`	Buscar usuario por nombre de usuario	`username`
`get_user_tweets`	Obtener las publicaciones recientes de un usuario	`username`, `limit`
`get_user_mentions`	Obtener publicaciones que mencionan a un usuario	`username`, `limit`
`get_user_liked_tweets`	Obtener las publicaciones con me gusta de un usuario	`username`, `limit`
`get_user_followers`	Obtener los seguidores de un usuario	`username`, `limit`
`get_user_following`	Obtener las cuentas que sigue un usuario	`username`, `limit`
`get_blocking_users`	Obtener usuarios bloqueados por la cuenta autenticada	`limit`
`get_muting_users`	Obtener usuarios silenciados por la cuenta autenticada	`limit`
`get_owned_lists`	Obtener listas propiedad de un usuario	`username`, `limit`
`get_followed_lists`	Obtener listas seguidas por un usuario	`username`, `limit`
`get_list_memberships`	Obtener listas a las que pertenece un usuario	`username`, `limit`

Artículos

Herramienta	Descripción	Parámetros clave
`get_article`	Obtener el contenido completo del cuerpo de una publicación de Artículo de X	`tweet_id`

Soporte de medios

Imágenes: PNG, JPEG, GIF, WEBP (máx. 5MB)
Videos: MP4, MOV, AVI, WEBM, M4V (máx. 512MB, carga por fragmentos en streaming)
No se pueden adjuntar imagen y video a la misma publicación
Requiere credenciales OAuth 2.0 (carga v1.1 retirada en junio de 2025)
Restricción de ruta: Solo se pueden cargar archivos dentro de tu directorio de inicio o el directorio temporal del sistema (evita el path traversal)

Seguridad

Validación de entrada: Los IDs de tweets deben ser numéricos (1-20 dígitos), los nombres de usuario deben coincidir con [A-Za-z0-9_]{1,15}
Restricción de ruta de medios: Las rutas de carga se validan contra una lista de permitidos (directorio de inicio, directorio temporal)
Almacenamiento de tokens: Los tokens OAuth 2.0 se guardan en ~/.x-mcp-tokens.json con permisos 0o600 (Unix). En Windows, el sistema operativo no aplica permisos de archivo: protege el archivo mediante ACL de NTFS o usa variables de entorno en su lugar.
Saneamiento de errores: Los detalles de error de la X API solo se registran en el servidor; se devuelven mensajes saneados a los clientes MCP
Mutex de renovación: Los intentos concurrentes de renovación de tokens se deduplican para evitar condiciones de carrera

Desarrollo

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server

Estructura del proyecto

src/
  index.ts              # MCP server entry point & handler dispatch
  client.ts             # Twitter client setup (OAuth 1.0a + OAuth 2.0)
  media.ts              # v2 media upload (simple + chunked)
  rate-limit.ts         # Per-endpoint rate limiting
  tools/
    definitions.ts      # All 16 tool schemas
    handlers.ts         # Tool handler implementations

Combinación con GetXAPI para operaciones de lectura más económicas (Opcional)

Para usuarios que necesitan una opción más económica o con mayor límite de velocidad para operaciones de solo lectura en Twitter (X), como búsqueda de tweets, consulta de perfiles y listas de seguidores, este proyecto se puede combinar con GetXAPI, una API de datos de Twitter / X económica con un precio de $0.05 por 1K tweets frente al nivel básico de la X API oficial a $200 / mes.

Dos patrones de integración:

Ejecutar en paralelo en tu cliente de IA. Mantén este proyecto para su flujo de trabajo principal y añade el servidor MCP oficial de GetXAPI para tareas con muchas lecturas. Cada nombre de herramienta se enruta al backend más adecuado para esa operación.
Añadir un interruptor de backend. Para una referencia a nivel de código de un backend alternativo opcional detrás de una sola variable de entorno, consulta el patrón de PR fusionado en un proyecto hermano.

Inicio rápido de GetXAPI:

Regístrate con $0.50 de crédito gratuito (sin tarjeta): https://getxapi.com/signup
Servidor MCP oficial de GetXAPI: https://github.com/getxapi/getxapi-mcp
npm: @getxapi/mcp
Precio por llamada: $0.001 / llamada, $0.05 / 1K tweets

Esta combinación es totalmente opcional. No cambia el comportamiento para los usuarios existentes.

Licencia

MIT

Contribuciones

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add some amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre un Pull Request