Twitter/X MCP

Twitter/X MCP permite a un cliente MCP leer publicaciones, respuestas y perfiles públicos de X, o buscar en X. Usa Rettiwt por defecto, por lo que no necesitas un plan de desarrollador de X. Puedes cambiar a la API oficial de X si tienes acceso.

Requisitos

• Node.js 22.21.0 o una versión más reciente dentro de la rama Node 22. La versión actual de Rettiwt no es compatible con Node 23 o posterior.

• Una RETTIWT_API_KEY. Las credenciales de la API oficial de X funcionan cuando seleccionas el modo API.

Related MCP server: MCP Twitter/X Server

Inicio rápido

Una vez que el paquete esté publicado, tu cliente MCP puede ejecutarlo sin necesidad de clonar el repositorio:

npx -y @granitebps/twitter-mcp

El servidor selecciona Rettiwt cuando omites TWITTER_MODE. Pasa RETTIWT_API_KEY en la configuración del cliente.

El servidor usa stdio. Mantén stdout reservado para el tráfico MCP.

Ejecutar desde un repositorio clonado

Para probar el servidor o usar un clon directamente:

git clone https://github.com/granitebps/twitter-mcp.git
cd twitter-mcp
npm ci
npm run build

Apunta tu cliente MCP al punto de entrada compilado:

node /absolute/path/to/twitter-mcp/dist/cli.js

Ejecuta npm run build después de cada cambio en el código fuente. No uses src ni npm run dev como comando stdio del cliente. Los registros de compilación en stdout pueden dañar los mensajes MCP.

Configuración del cliente

Cada ejemplo comienza con el paquete npm y luego el equivalente local. Reemplaza /absolute/path/to/twitter-mcp por la ruta de tu clon y your_key_here por tu clave Rettiwt. No hagas commit de un archivo de configuración que contenga la clave.

Claude

Añade el paquete npm a Claude Code:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

Para una compilación local:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code usa el ámbito local por defecto. Añade --scope user antes de twitter para que el servidor esté disponible en todos los proyectos.

Claude Desktop lee el mismo servidor desde claude_desktop_config.json. Reinicia la aplicación después de editar el archivo.

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Para una compilación local, reemplaza command y args por:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Codex

Añade el paquete npm a ~/.codex/config.toml, o a .codex/config.toml en un proyecto de confianza:

[mcp_servers.twitter]
command = "npx"
args = ["-y", "@granitebps/twitter-mcp"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

Para una compilación local:

[mcp_servers.twitter]
command = "node"
args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

Reinicia Codex después de editar el archivo. La CLI, la extensión del IDE y la aplicación de escritorio comparten esta configuración en el mismo ordenador.

OpenCode

Añade el paquete npm a opencode.json o opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twitter": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
      "enabled": true,
      "environment": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Para una compilación local, reemplaza el array command por:

{
  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Cursor

Añade el paquete npm a .cursor/mcp.json en un proyecto, o a ~/.cursor/mcp.json para uso global:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Para una compilación local, reemplaza command y args por:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Proveedores

Configuración de Rettiwt

Rettiwt requiere el modo de usuario autenticado en este servidor. El modo de invitado no está soportado.

1. Genera una clave API con las instrucciones de autenticación de Rettiwt.

2. Almacena la clave como RETTIWT_API_KEY en el entorno del cliente MCP.

3. Inicia el servidor sin TWITTER_MODE, o establece TWITTER_MODE=rettiwt explícitamente.

Una clave Rettiwt contiene cookies de sesión de X y tiene el mismo acceso que la cuenta. Trátala como una contraseña. No la confirmes en el repositorio, no la pegues en un issue, no la registres en logs ni la pases como argumento de línea de comandos. Usa una clave solo para una cuenta que sea tuya o para la que tengas permiso de acceso.

Rettiwt no es oficial. Las normas de automatización de X prohíben la automatización web no basada en la API y advierten de que puede haber suspensiones de cuenta por incumplimiento. Lee las Reglas de X antes de usar este modo. Aceptas el riesgo de cumplimiento normativo y de cuenta.

Configuración de la API oficial de X

Usa un token bearer:

TWITTER_MODE=api
TWITTER_BEARER_TOKEN=your_bearer_token

O proporciona el conjunto completo de credenciales OAuth:

TWITTER_MODE=api
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

Crea las credenciales en el Portal de desarrolladores de X. X controla el acceso a la API y el precio, así que consulta los términos actuales antes de elegir este modo.

Configuración

El servidor rechaza una configuración OAuth incompleta al iniciarse. Lee las credenciales del entorno del proceso y nunca las devuelve a través de get_server_info.

Herramientas

max_results está por defecto en 10 y admite valores de 1 a 100. Los clientes más antiguos reciben texto JSON aparte del contenido MCP estructurado. Las herramientas de colección devuelven los elementos como texto JSON y colocan los cursores y advertencias en el contenido estructurado.

Errores

Los fallos de las herramientas usan códigos estables:

• INVALID_INPUT

• AUTH_REQUIRED

• AUTH_FAILED

• NOT_FOUND

• RATE_LIMITED

• ORIGIN_SERVER_503

• TIMEOUT

• UNSUPPORTED_OPERATION

• INTERNAL_ERROR

Los errores indican el proveedor e informan de si un reintento puede funcionar. No incluyen credenciales ni cuerpos de respuesta crudos del proveedor de origen.

Arquitectura

stdio CLI
  -> validated environment configuration
  -> MCP server and tool handlers
  -> TwitterProvider contract
       -> Rettiwt adapter
       -> official X API adapter

Los esquemas de dominio no dependen de ningún proveedor. Cada adaptador de proveedor transforma los datos del proveedor, aplica límites y plazos, y traduce los errores. Importar src/index.ts no inicia el servidor.

Desarrollo

npm ci
npm run check

npm run check comprueba el formato, la gran variedad de código, tipos, cobertura, compilación de producción, el contenido del paquete npm y la instalación limpia del tarball. La suite de pruebas normal usa simulaciones y no necesita las credenciales de X.

Comandos útiles centrados en:

npm test
npm run typecheck
npm run lint
npm run build
npm run check:package
npm run check:install
npx @modelcontextprotocol/inspector node dist/cli.js

Prueba de humo en vivo de Rettiwt

La prueba de humo en vivo inicia el servidor stdio compilado y llama get_tweet, get_tweet_replies, get_user_profile y search_tweets. Coloca el nombre de usuario y la consulta de búsqueda a partir de la publicación seleccionada.

RETTIWT_API_KEY=your_key_here \
TWITTER_LIVE_TWEET_ID=1234567890123456789 \
npm run test:live

Elige una publicación pública cuyo perfil del autor esté todavía disponible. Si falta alguna de las dos variables, el comando se detiene antes de iniciar el servidor en vivo o realizar una solicitud de red. No se ejecuta como parte de npm run check ni del CI normal.

Verificación de lanzamiento

La suite automatizada cubre la configuración, los adaptadores de proveedor, las llamadas MCP, el punto de entrada stdio compilado y la instalación desde un tarball de npm. La prueba de humo en vivo de Rettiwt es opcional y no se ejecuta en el CI normal. La versión 1.0.0 se preparó sin verificación en vivo de los proveedores.

Los responsables del proyecto pueden seguir la guía de la publicación para el proceso de publicación manual de npm, los permisos del MCP Registry y las GitHub. Las pruebas en vivo deben leer las credenciales de encriptación de los repositorios y no deben ejecutarse para pull requests de no confianza.

Solución de problemas

Falta la clave de Rettiwt

Si el inicio muestra elección RETTIWT_API_KEY es necesario en el modo Rettiwt, pon la clave en la configuración del cliente MCP. Los clientes de escritorio no obtienen automáticamente el archivo .env de tu shell.

Autenticación de Rettiwt no válida

Si ves Invalid authentication data o AUTH_FAILED, genera una nueva clave de Rettiwt y comprueba que la sesión de X sigue funcionando. Nunca publiques la clave que falla en un issue.

Límite de uso

Para RATE_LIMITED, espera antes de volver a intentarlo y reduce la tasa de peticiones. Consulta retryAfterSeconds si el proveedor la proporciona.

API oficial 401 o 403

Confirma el conjunto de credenciales, los permisos de la aplicación, el acceso al endpoint y el plan actual de la API de X.

Aviso sobre el motor Node

Ejecuta Node.js 22.21.0 o una versión más nueva de Node 22. No uses Node 23 o posterior con la dependencia Rettiwt actual.

Licencia

ISC