X (Twitter)

Servidor MCP mejorado para Twitter/X con soporte OAuth 2.0, carga de medios en la API v2, fallbacks inteligentes v1.1 y limitación de tasa completa. Publica tweets con texto/medios, busca y elimina tweets de forma programática.

GitHub
24

Documentación

Servidor MCP de X - Edición Mejorada

npm version

Un servidor de Protocolo de Contexto de Modelo (MCP) mejorado para X que añade soporte OAuth 2.0, subida de medios con API v2 y limitación de tasa integral a la implementación original.

✨ Características

  • Publicar Tweets: Crea tweets de texto con archivos multimedia opcionales (imágenes, GIFs)
  • Buscar Tweets: Busca en X con un número de resultados personalizable
  • Eliminar Tweets: Elimina tus tweets programáticamente
  • Autenticación Dual: Soporte tanto para OAuth 1.0a como para OAuth 2.0
  • Subida de Medios: Publica imágenes usando la versión de API apropiada para cada método de autenticación
  • Limitación de Tasa: Protección integrada para los límites de API de X
  • Seguridad de Tipos: Implementación completa en TypeScript con validación Zod

🔄 Manejo de Versiones de API

Este servidor utiliza de forma inteligente diferentes versiones de la API de X según el método de autenticación y la operación:

OAuth 1.0a

  • Operaciones de tweets: Utiliza endpoints de la API v2
  • Subida de medios: Utiliza el endpoint v1.1 (upload.twitter.com)
  • Respaldo de eliminación: Vuelve automáticamente a v1.1 cuando v2 falla

OAuth 2.0

  • Todas las operaciones: Utiliza exclusivamente endpoints de la API v2
  • Subida de medios: Utiliza el endpoint v2 (api.x.com/2/media/upload)
  • Sin acceso a v1.1: No puede recurrir a v1.1 debido a restricciones de autenticación

¿Por qué diferentes endpoints?

  • v1.1: API heredada, en proceso de eliminación pero aún funciona con OAuth 1.0a
  • v2: API moderna con mejores características pero algunos endpoints tienen problemas
  • Medios: Los tokens OAuth 2.0 no pueden acceder a los endpoints de medios v1.1, deben usar v2
  • Eliminación: El endpoint de eliminación v2 actualmente tiene problemas (errores 500), v1.1 funciona como respaldo

📋 Requisitos Previos

Antes de comenzar, necesitarás:

  1. Una Cuenta de Desarrollador de X (regístrate en developer.x.com)
  2. Una App de X creada en el Portal de Desarrolladores
  3. Credenciales de API (configuración detallada abajo)
  4. Node.js 18+ instalado

🔐 Configuración de Autenticación

Este servidor admite dos métodos de autenticación. Elige según tus necesidades:

  • OAuth 1.0a: Configuración más simple, funciona con todas las características incluyendo respaldos v1.1
  • OAuth 2.0: Autenticación moderna, requerida para algunas características más nuevas

Configurando Tu App de X

  1. Crea una Cuenta de Desarrollador:

    • Ve a developer.x.com
    • Inicia sesión con tu cuenta de Twitter
    • Solicita acceso de desarrollador si aún no lo tienes

  2. Crea una Nueva App:

    • Navega al Portal de Desarrolladores de Twitter
    • Haz clic en "Projects & Apps" → "New Project"
    • Dale un nombre a tu proyecto
    • Selecciona tu caso de uso
    • Crea una nueva App dentro del proyecto

  3. Configura los Permisos de la App:

    • En la configuración de tu app, ve a "User authentication settings"
    • Haz clic en "Set up"
    • Habilita OAuth 1.0a y/o OAuth 2.0
    • Establece los permisos de la App en "Read and write"
    • Añade URLs de devolución de llamada:
      • Para OAuth 1.0a: http://localhost:3000/callback
      • Para OAuth 2.0: http://localhost:3000/callback
    • Establece la URL del sitio web (puede ser tu repositorio de GitHub)

Configuración de OAuth 1.0a

  1. Obtén Tus Credenciales:

    • En la pestaña "Keys and tokens" de tu app
    • Copia tu API Key y API Key Secret
    • Genera el Access Token y Secret (haz clic en "Generate")
    • Asegúrate de que el token de acceso tenga permisos de "Read and Write"

  2. Credenciales Requeridas:

    API_KEY=your_api_key_here
API_SECRET_KEY=your_api_secret_key_here
ACCESS_TOKEN=your_access_token_here
ACCESS_TOKEN_SECRET=your_access_token_secret_here

Configuración de OAuth 2.0

  1. Obtén Tus Credenciales de Cliente:

    • En la pestaña "Keys and tokens" de tu app
    • Encuentra el OAuth 2.0 Client ID y Client Secret
    • Guárdalos para el siguiente paso

  2. Genera Tokens de Usuario:

    Opción A - Usa nuestro script auxiliar:

    # Clone this repository first
git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

# Run the OAuth2 setup script
node scripts/oauth2-setup.js

    Opción B - Configuración manual:

    • Usa el flujo OAuth 2.0 con PKCE
    • Ámbitos requeridos: tweet.read, tweet.write, users.read, media.write, offline.access
    • Intercambia el código de autorización por un token de acceso

  3. Credenciales Requeridas:

    AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id_here
OAUTH2_CLIENT_SECRET=your_client_secret_here
OAUTH2_ACCESS_TOKEN=your_access_token_here
OAUTH2_REFRESH_TOKEN=your_refresh_token_here

🚀 Instalación

Para Claude Desktop

  1. Instala vía NPM (Recomendado):

    Edita tu archivo de configuración de Claude Desktop:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    Añade esta configuración:

    {
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_SECRET_KEY": "your_api_secret_key_here",
        "ACCESS_TOKEN": "your_access_token_here",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
      }
    }
  }
}

    Para OAuth 2.0:

    {
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "AUTH_TYPE": "oauth2",
        "OAUTH2_CLIENT_ID": "your_client_id",
        "OAUTH2_CLIENT_SECRET": "your_client_secret",
        "OAUTH2_ACCESS_TOKEN": "your_access_token",
        "OAUTH2_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

  2. Instala desde el Código Fuente:

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

    Luego actualiza tu configuración para apuntar a la instalación local:

    {
  "mcpServers": {
    "twitter-mcp": {
      "command": "node",
      "args": ["/path/to/twitter-mcp/build/index.js"],
      "env": {
        // ... your credentials
      }
    }
  }
}

  3. Reinicia Claude Desktop

Para Claude Code (CLI)

Instala el servidor globalmente y añádelo a Claude:

# For OAuth 1.0a
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "API_KEY=your_api_key" \
  --env "API_SECRET_KEY=your_secret_key" \
  --env "ACCESS_TOKEN=your_access_token" \
  --env "ACCESS_TOKEN_SECRET=your_access_token_secret"

# For OAuth 2.0
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "AUTH_TYPE=oauth2" \
  --env "OAUTH2_CLIENT_ID=your_client_id" \
  --env "OAUTH2_CLIENT_SECRET=your_client_secret" \
  --env "OAUTH2_ACCESS_TOKEN=your_access_token" \
  --env "OAUTH2_REFRESH_TOKEN=your_refresh_token"

🛠️ Herramientas Disponibles

Una vez instalado, Claude puede usar estas herramientas:

post_tweet

Publica un nuevo tweet con archivos multimedia opcionales y respuestas.

Ejemplos de indicaciones:

  • "Publica un tweet que diga '¡Hola desde Claude!'"
  • "Tuitea esta imagen con el título '¡Mira esta vista!'" (adjunta imagen)
  • "Responde al tweet ID 123456789 con '¡Buen punto!'"

search_tweets

Busca tweets con un número de resultados personalizable (10-100).

Ejemplos de indicaciones:

  • "Busca tweets sobre #MachineLearning"
  • "Encuentra 50 tweets recientes que mencionen a @ClaudeAI"
  • "Busca tweets sobre tutoriales de TypeScript"

delete_tweet

Elimina un tweet por su ID.

Ejemplos de indicaciones:

  • "Elimina el tweet con ID 1234567890"
  • "Elimina mi último tweet (proporciona el ID)"

Nota: Debido a problemas temporales de la API de Twitter, OAuth 1.0a usa el respaldo v1.1 para la eliminación.

📸 Notas sobre Subida de Medios

Cuando uses Claude para publicar tweets con imágenes:

  • Usa rutas de archivo: Guarda tu imagen en el disco y proporciona la ruta del archivo
  • Limitación de Base64: Aunque el servidor admite imágenes codificadas en base64, Claude no puede extraer base64 de imágenes pegadas
  • Otros clientes: El soporte base64 sigue disponible para uso programático y otros clientes MCP

Ejemplo de uso:

# ✅ Recommended for Claude
"Post tweet with image at /Users/me/photos/sunset.png"

# ❌ Not currently supported in Claude
"Post this image: [pasting an image directly]"

# ✅ Works programmatically
// In code, you can still use base64
{
  "text": "Hello world!",
  "media": [{
    "data": "iVBORw0KGgoAAAANS...",
    "media_type": "image/png"
  }]
}

🧪 Pruebas

El proyecto incluye pruebas exhaustivas:

# Run all tests
npm test

# Run specific test suites
npm test -- --testNamePattern="OAuth"
npm test -- --testPathPattern="unit"

🔧 Desarrollo

Configuración

git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

Comandos

npm run build    # Build TypeScript
npm run dev      # Run in development mode
npm test         # Run tests
npm run lint     # Lint code
npm run format   # Format code

Variables de Entorno

Crea un archivo .env para el desarrollo local:

# OAuth 1.0a
API_KEY=your_api_key
API_SECRET_KEY=your_api_secret_key
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

# OAuth 2.0 (if using)
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_ACCESS_TOKEN=your_access_token
OAUTH2_REFRESH_TOKEN=your_refresh_token

# Optional
DEBUG=true  # Enable debug logging

✅ Soporte de Subida de Medios con OAuth 2.0

¡La subida de medios ahora funciona tanto con OAuth 1.0a como con OAuth 2.0!

  • OAuth 1.0a usa el endpoint de subida de medios v1.1 ✓
  • OAuth 2.0 usa el endpoint de subida de medios v2 ✓
  • Ambos métodos de autenticación admiten publicar tweets con imágenes (JPEG, PNG, GIF)

Nota: OAuth 2.0 requiere el ámbito media.write para la subida de medios.

⚠️ Problemas Conocidos

Eliminación de Tweets (Temporal)

El endpoint de eliminación v2 de Twitter está experimentando problemas actualmente (devolviendo errores 500). El servidor MCP maneja esto con elegancia:

  • OAuth 1.0a: Vuelve automáticamente al endpoint de eliminación v1.1 ✅
  • OAuth 2.0: No puede usar el endpoint v1.1, mostrará un mensaje de error útil ⚠️

Este es un problema temporal de la API de Twitter. Una vez resuelto, ambos métodos de autenticación usarán la eliminación v2.

🐛 Solución de Problemas

Problemas Comunes

"Could not authenticate you"

  • Verifica que todas las credenciales sean correctas
  • Comprueba que tu app tenga permisos de "Read and Write"
  • Para OAuth 1.0a, regenera tus tokens de acceso
  • Para OAuth 2.0, asegúrate de que los tokens tengan los ámbitos requeridos

"Rate limit exceeded"

  • Twitter tiene límites de tasa estrictos (especialmente en el nivel gratuito)
  • Espera 15 minutos e inténtalo de nuevo
  • Considera actualizar tu nivel de acceso a la API de Twitter

"Media upload failed"

  • Comprueba el tamaño del archivo (máximo 5MB para imágenes)
  • Verifica el formato del archivo (solo JPEG, PNG, GIF)
  • Para OAuth 2.0, asegúrate de que el ámbito media.write esté incluido

"403 Forbidden"

  • Tu app puede carecer de los permisos requeridos
  • Revisa la configuración de tu Portal de Desarrolladores de Twitter
  • Asegúrate de que tu nivel de acceso admita la operación

Modo de Depuración

Habilita el registro detallado estableciendo la variable de entorno DEBUG:

{
  "env": {
    "DEBUG": "true",
    // ... other credentials
  }
}

Ubicaciones de Registros

  • Windows: %APPDATA%\Claude\logs\mcp-server-twitter.log
  • macOS: ~/Library/Logs/Claude/mcp-server-twitter.log

📚 Recursos

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Añade pruebas para la nueva funcionalidad
  4. Asegúrate de que todas las pruebas pasen
  5. Envía una solicitud de extracción

🔒 Política de Privacidad

Este servidor MCP:

  • No almacena ningún dato de usuario: Todas las credenciales de la API de Twitter/X se almacenan localmente en tu máquina
  • No registra información sensible: Las claves de API y tokens nunca se registran
  • Solo se comunica con Twitter/X: No se envían datos a servicios de terceros
  • Procesa datos localmente: Todas las operaciones ocurren en tu máquina
  • Respeta los límites de tasa: Protección integrada para los límites de API de Twitter

Tus tweets, búsquedas y medios permanecen privados entre tú y Twitter/X.

📧 Soporte

Para vulnerabilidades de seguridad, envía un correo electrónico directamente en lugar de crear un problema público.

📄 Licencia

MIT

🙏 Agradecimientos

Esta es una bifurcación mejorada de @enescinar/twitter-mcp que añade:

  • Soporte de autenticación OAuth 2.0
  • Subida de medios con API v2 de Twitter/X para OAuth 2.0
  • Respaldo automático v1.1 para OAuth 1.0a
  • Limitación de tasa integral para el nivel gratuito
  • Manejo de errores y depuración mejorados
  • Script programático de generación de tokens OAuth 2.0

Implementación original por @enescinar