X (Twitter)

Un servidor MCP para interactuar con la API de X (Twitter), que requiere credenciales de desarrollador.

GitHub
35
Prueba este MCPPatrocinado

Documentación

X (Twitter) MCP server

smithery badge PyPI version

Un servidor de Model Context Protocol (MCP) para interactuar con Twitter (X) mediante herramientas de IA. Este servidor te permite obtener tweets, publicar tweets, buscar en Twitter, gestionar seguidores y más, todo a través de comandos en lenguaje natural en herramientas de IA.

X (Twitter) server MCP server

Características

  • Obtener perfiles de usuario, seguidores y listas de seguidos.
  • Publicar, eliminar y marcar como favoritos tweets.
  • Buscar en Twitter tweets y tendencias.
  • Gestionar marcadores y cronologías.
  • Manejo integrado de límites de tasa para la API de Twitter.
  • Utiliza la API v2 de Twitter con autenticación adecuada (claves y tokens de API), evitando el hack de usuario/contraseña para minimizar el riesgo de suspensiones de cuenta.
  • Proporciona una implementación completa de los endpoints de la API v2 de Twitter para gestión de usuarios, gestión de tweets, cronologías y funcionalidad de búsqueda.

Requisitos previos

  • Python 3.10 o superior: Asegúrate de tener Python instalado en tu sistema.
  • Cuenta de desarrollador de Twitter: Necesitas credenciales de API (API Key, API Secret, Access Token, Access Token Secret y Bearer Token) del Twitter Developer Portal.
  • Opcional: Claude Desktop: Descarga e instala la aplicación Claude Desktop desde el sitio web de Anthropic.
  • Opcional: Node.js (para integración MCP): Requerido para ejecutar servidores MCP en Claude Desktop.
  • Un gestor de paquetes como uv o pip para dependencias de Python.

Instalación

Opción 1: Instalación mediante Smithery (Recomendado)

Para instalar el servidor X (Twitter) MCP para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @rafaljanicki/x-twitter-mcp-server --client claude

Opción 2: Instalar desde PyPI

La forma más fácil de instalar x-twitter-mcp es mediante PyPI:

pip install x-twitter-mcp

Opción 3: Instalar desde el código fuente

Si prefieres instalar desde el repositorio fuente:

  1. Clonar el repositorio:

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

  2. Configurar un entorno virtual (opcional pero recomendado):

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instalar dependencias: Usando uv (recomendado, ya que el proyecto usa uv.lock):

    uv sync

    Alternativamente, usando pip:

    pip install .

  4. Configurar variables de entorno:

    • Crea un archivo .env en la raíz del proyecto (puedes copiar .env.example si se proporciona).
    • Añade tus credenciales de la API de Twitter: 
      TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
TWITTER_BEARER_TOKEN=your_bearer_token
    • Para usar herramientas de marcadores (get_bookmarks, delete_all_bookmarks), añade también un token de acceso de usuario OAuth 2.0: 
      TWITTER_OAUTH2_USER_ACCESS_TOKEN=your_oauth2_user_token
      Consulta Obtención de un token de usuario OAuth 2.0 a continuación.

Obtención de un token de usuario OAuth 2.0

Los endpoints de marcadores (GET /2/users/:id/bookmarks, DELETE /2/users/:id/bookmarks/:tweet_id) requieren Contexto de usuario OAuth 2.0 — rechazan tanto los tokens de portador solo de aplicación como OAuth 1.0a. Debes realizar el flujo de autorización PKCE una vez para obtener un token con ámbito de usuario.

Pasos

  1. En el Twitter Developer Portal, abre tu aplicación → Configuración → Configuración de autenticación de usuario y habilita OAuth 2.0. Establece una URL de devolución de llamada (por ejemplo, https://localhost/).

  2. Ejecuta el flujo PKCE usando Tweepy:

import tweepy

handler = tweepy.OAuth2UserHandler(
    client_id="YOUR_CLIENT_ID",       # OAuth 2.0 Client ID (from Developer Portal)
    redirect_uri="https://localhost/",
    scope=["bookmark.read", "bookmark.write", "users.read", "offline.access"],
    client_secret="YOUR_CLIENT_SECRET",  # Optional for public clients
)

print(handler.get_authorization_url())
# Open the URL, authorize, copy the redirected URL, then:
redirected_url = input("Paste redirected URL: ")
token = handler.fetch_token(redirected_url)
print(token["access_token"])
  1. Establece el token resultante como TWITTER_OAUTH2_USER_ACCESS_TOKEN en tu entorno o archivo .env.

Ejecutar el servidor

El transporte preferido es Streamable HTTP. Usa una de las siguientes opciones:

Recomendado: Streamable HTTP (Docker/Smithery)

Ejecuta el servidor como un servicio HTTP con endpoints Streamable HTTP y SSE.

  1. Construye la imagen de Docker:

    docker build -t x-twitter-mcp .

  2. Ejecuta el contenedor (Smithery usa PORT; el valor predeterminado aquí es 8081):

    docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp

  3. Endpoints:

    • Streamable HTTP (JSON-RPC sobre HTTP): POST http://localhost:8081/mcp
    • SSE (Server-Sent Events): GET http://localhost:8081/sse

  4. Pasa la configuración por solicitud (recomendado en Smithery) mediante el parámetro de consulta config codificado en base64. Ejemplo de configuración JSON:

    {"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}

    Codifica y llama a initialize:

    CONFIG_B64=$(printf '%s' '{"twitterApiKey":"YOUR_KEY","twitterApiSecret":"YOUR_SECRET","twitterAccessToken":"YOUR_TOKEN","twitterAccessTokenSecret":"YOUR_TOKEN_SECRET","twitterBearerToken":"YOUR_BEARER"}' | base64)

curl -sS -X POST "http://localhost:8081/mcp?config=${CONFIG_B64}" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}}}'

Notas:

  • Un POST / devolverá 404; usa /mcp para Streamable HTTP y /sse para SSE.
  • Cuando se implementa mediante Smithery, smithery.yaml está configurado para runtime: container y startCommand.type: http.

Streamable HTTP (Local, sin Docker)

Ejecuta el servidor ASGI directamente.

Si se instala desde PyPI:

python -m x_twitter_mcp.http_server

Si se instala desde el código fuente con uv:

uv run python -m x_twitter_mcp.http_server

Los endpoints y el paso de configuración son los mismos que arriba.

STDIO heredado (script CLI)

El proyecto también expone un script CLI STDIO x-twitter-mcp-server para clientes de escritorio que esperan STDIO.

Si se instala desde PyPI:

x-twitter-mcp-server

Si se instala desde el código fuente con uv:

uv run x-twitter-mcp-server

Uso con Claude Desktop

Para usar este servidor MCP con Claude Desktop, debes configurar Claude para conectarse al servidor. Sigue estos pasos:

Paso 1: Instalar Node.js

Claude Desktop usa Node.js para ejecutar servidores MCP. Si no tienes Node.js instalado:

  • Descarga e instala Node.js desde nodejs.org.
  • Verifica la instalación: 
    node --version

Paso 2: Localizar la configuración de Claude Desktop

Claude Desktop usa un archivo claude_desktop_config.json para configurar servidores MCP.

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

Si el archivo no existe, créalo.

Paso 3: Configurar el servidor MCP

Edita claude_desktop_config.json para incluir el servidor x-twitter-mcp. Reemplaza /path/to/x-twitter-mcp-server con la ruta real a tu directorio del proyecto (si se instaló desde el código fuente) o la ruta a tu ejecutable de Python (si se instaló desde PyPI).

Si se instala desde PyPI:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token",
        "TWITTER_OAUTH2_USER_ACCESS_TOKEN": "your_oauth2_user_token"
      }
    }
  }
}

Si se instala desde el código fuente con uv:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
  • "command": "x-twitter-mcp-server": Usa el script CLI directamente si se instala desde PyPI.
  • "env": Si se instala desde PyPI, es posible que debas proporcionar variables de entorno directamente en la configuración (ya que no hay archivo .env). Si se instala desde el código fuente, se usará el archivo .env.
  • "env": {"PYTHONUNBUFFERED": "1"}: Asegura que la salida no esté almacenada en búfer para un mejor registro en Claude.

Paso 4: Reiniciar Claude Desktop

  • Cierra Claude Desktop por completo.
  • Vuelve a abrir Claude Desktop para cargar la nueva configuración.

Paso 5: Verificar la conexión

  • Abre Claude Desktop.
  • Busca un icono de martillo o conector en el área de entrada (esquina inferior derecha). Esto indica que las herramientas MCP están disponibles.
  • Haz clic en el icono para ver las herramientas disponibles de x-twitter-mcp, como post_tweet, search_twitter, get_user_profile, etc.

Paso 6: Probar con Claude

Ahora puedes interactuar con Twitter usando lenguaje natural en Claude Desktop. Aquí tienes algunos ejemplos de indicaciones:

  • Obtener un perfil de usuario:

    Get the Twitter profile for user ID 123456.

    Claude llamará a la herramienta get_user_profile y devolverá los detalles del usuario.

  • Publicar un tweet:

    Post a tweet saying "Hello from Claude Desktop! #MCP"

    Claude usará la herramienta post_tweet para publicar el tweet y confirmar la acción.

  • Buscar en Twitter:

    Search Twitter for recent tweets about AI.

    Claude invocará la herramienta search_twitter y devolverá los tweets relevantes.

  • Obtener tendencias:

    What are the current trending topics on Twitter?

    Claude usará la herramienta get_trends para obtener los temas de tendencia.

Cuando se te solicite, concede a Claude permiso para usar las herramientas MCP para la sesión de chat.

Flujo de trabajo complementario de OpenClaw

Este servidor MCP es mejor cuando un cliente MCP debe llamar directamente a las herramientas de la API v2 de Twitter. Si el flujo de trabajo se ejecuta en OpenClaw y necesita metadatos de instalación de plugins, descubrimiento de endpoints, alertas de monitoreo, webhooks, sorteos, flujos de trabajo de carga o descarga de medios, mensajes directos, exportación de seguidores o acciones de publicación y respuesta con aprobación, usa TweetClaw como un plugin separado de OpenClaw y pasa los IDs o URLs de tweets revisados entre las herramientas.

Consulta Flujo de trabajo complementario de OpenClaw para un flujo de comandos que mantiene las credenciales separadas y evita acciones de escritura duplicadas.

Herramientas disponibles

A continuación se muestra una lista de todas las herramientas proporcionadas por el servidor x-twitter-mcp, junto con ejemplos de ejecución en Claude Desktop usando indicaciones en lenguaje natural.

Herramientas de gestión de usuarios

get_user_profile

  • Descripción: Obtén información detallada del perfil de un usuario.
  • Ejemplo en Claude Desktop: 
    Get the Twitter profile for user ID 123456789.
    Claude devolverá los detalles del perfil del usuario, incluidos ID, nombre, nombre de usuario, URL de la imagen de perfil y descripción.

get_user_by_screen_name

  • Descripción: Obtiene un usuario por nombre de pantalla.
  • Ejemplo en Claude Desktop: 
    Get the Twitter user with screen name "example_user".
    Claude devolverá los detalles del perfil del usuario.

get_user_by_id

  • Descripción: Obtiene un usuario por ID.
  • Ejemplo en Claude Desktop: 
    Fetch the Twitter user with ID 987654321.
    Claude devolverá los detalles del perfil del usuario.

get_user_followers

  • Descripción: Recupera una lista de seguidores de un usuario determinado.
  • Ejemplo en Claude Desktop: 
    Get the followers of user ID 123456789, limit to 50.
    Claude devolverá una lista de hasta 50 seguidores.

get_user_following

  • Descripción: Recupera los usuarios que el usuario determinado sigue.
  • Ejemplo en Claude Desktop: 
    Who is user ID 123456789 following? Limit to 50 users.
    Claude devolverá una lista de hasta 50 usuarios.

get_user_followers_you_know

  • Descripción: Recupera una lista de seguidores comunes.
  • Ejemplo en Claude Desktop: 
    Get common followers for user ID 123456789, limit to 50.
    Claude devolverá una lista de hasta 50 seguidores comunes (simulados filtrando seguidores).

get_user_subscriptions

  • Descripción: Recupera una lista de usuarios a los que el usuario especificado está suscrito.
  • Ejemplo en Claude Desktop: 
    Get the subscriptions for user ID 123456789, limit to 50.
    Claude devolverá una lista de hasta 50 usuarios (usando seguidos como proxy para suscripciones).

Herramientas de gestión de tweets

post_tweet

  • Descripción: Publica un tweet con medios, respuesta y etiquetas opcionales.
  • Ejemplo en Claude Desktop: 
    Post a tweet saying "Hello from Claude Desktop! #MCP"
    Claude publicará el tweet y devolverá los detalles del tweet.

delete_tweet

  • Descripción: Elimina un tweet por su ID.
  • Ejemplo en Claude Desktop: 
    Delete the tweet with ID 123456789012345678.
    Claude eliminará el tweet y confirmará la acción.

get_tweet_details

  • Descripción: Obtén información detallada sobre un tweet específico.
  • Ejemplo en Claude Desktop: 
    Get details for tweet ID 123456789012345678.
    Claude devolverá los detalles del tweet, incluidos ID, texto, fecha de creación e ID del autor.

create_poll_tweet

  • Descripción: Crea un tweet con una encuesta.
  • Ejemplo en Claude Desktop: 
    Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.
    Claude creará el tweet de encuesta y devolverá los detalles del tweet.

vote_on_poll

  • Descripción: Vota en una encuesta.
  • Ejemplo en Claude Desktop: 
    Vote "Blue" on the poll in tweet ID 123456789012345678.
    Claude devolverá una respuesta simulada (ya que la API v2 de Twitter no admite votación en encuestas).

favorite_tweet

  • Descripción: Marca un tweet como favorito.
  • Ejemplo en Claude Desktop: 
    Like the tweet with ID 123456789012345678.
    Claude marcará el tweet como favorito y confirmará la acción.

unfavorite_tweet

  • Descripción: Quita el favorito de un tweet.
  • Ejemplo en Claude Desktop: 
    Unlike the tweet with ID 123456789012345678.
    Claude quitará el favorito del tweet y confirmará la acción.

bookmark_tweet

  • Descripción: Añade el tweet a los marcadores.
  • Ejemplo en Claude Desktop: 
    Bookmark the tweet with ID 123456789012345678.
    Claude añadirá el tweet a los marcadores y confirmará la acción.

delete_bookmark

  • Descripción: Elimina el tweet de los marcadores.
  • Ejemplo en Claude Desktop: 
    Remove the bookmark for tweet ID 123456789012345678.
    Claude eliminará el marcador y confirmará la acción.

delete_all_bookmarks

  • Descripción: DESTRUCTIVO E IRREVERSIBLE. Elimina permanentemente TODOS los marcadores obteniendo cada página y eliminándolos uno por uno. Requiere TWITTER_OAUTH2_USER_ACCESS_TOKEN.
  • Ejemplo en Claude Desktop: 
    Delete all my Twitter bookmarks.
    Claude confirmará primero con el usuario, luego eliminará todos los marcadores e informará el recuento.

get_bookmarks

  • Descripción: Recupera los tweets marcados del usuario autenticado. Devuelve hasta 100 tweets por llamada; usa el parámetro cursor para la paginación. Requiere TWITTER_OAUTH2_USER_ACCESS_TOKEN.
  • Ejemplo en Claude Desktop: 
    Show my Twitter bookmarks, limit to 25.
    Claude devolverá hasta 25 tweets marcados, incluidos ID, texto, fecha de creación e ID del autor.

Herramientas de cronología y búsqueda

get_timeline

  • Descripción: Obtén tweets de tu cronología de inicio (Para ti).
  • Ejemplo en Claude Desktop: 
    Show my Twitter For You timeline, limit to 20 tweets.
    Claude devolverá hasta 20 tweets de tu cronología Para ti.

get_latest_timeline

  • Descripción: Obtén tweets de tu línea de tiempo de inicio (Siguiendo).
  • Ejemplo de Claude Desktop: 
    Show my Twitter Following timeline, limit to 20 tweets.
    Claude devolverá hasta 20 tweets de tu línea de tiempo de Siguiendo.

search_twitter

  • Descripción: Busca en Twitter con una consulta.
  • Ejemplo de Claude Desktop: 
    Search Twitter for recent tweets about AI, limit to 10.
    Claude devolverá hasta 10 tweets recientes sobre IA.

get_trends

  • Descripción: Recupera los temas de tendencia en Twitter.
  • Ejemplo de Claude Desktop: 
    What are the current trending topics on Twitter? Limit to 10.
    Claude devolverá hasta 10 temas de tendencia.

get_highlights_tweets

  • Descripción: Recupera tweets destacados de la línea de tiempo de un usuario.
  • Ejemplo de Claude Desktop: 
    Get highlighted tweets from user ID 123456789, limit to 20.
    Claude devolverá hasta 20 tweets de la línea de tiempo del usuario (simulados como destacados).

get_user_mentions

  • Descripción: Obtén tweets que mencionan a un usuario específico.
  • Ejemplo de Claude Desktop: 
    Get tweets mentioning user ID 123456789, limit to 20.
    Claude devolverá hasta 20 tweets que mencionan al usuario.

Solución de problemas

  • El servidor no se inicia:

    • Asegúrate de que tu archivo .env tenga todas las credenciales necesarias de la API de Twitter (si está instalado desde el código fuente).
    • Si está instalado desde PyPI, asegúrate de que las variables de entorno estén configuradas en claude_desktop_config.json o en tu shell.
    • Revisa la salida del terminal en busca de errores al ejecutar x-twitter-mcp-server.
    • Verifica que uv o tu ejecutable de Python esté correctamente instalado y sea accesible.

  • Claude no detecta el servidor:

    • Confirma que la ruta en claude_desktop_config.json sea correcta.
    • Asegúrate de que command y args apunten al ejecutable y al script correctos.
    • Reinicia Claude Desktop después de actualizar el archivo de configuración.
    • Revisa los registros del Modo Desarrollador de Claude (Ayuda → Habilitar Modo Desarrollador → Abrir Archivo de Registro de MCP) para ver errores.

  • Errores de límite de tasa:

    • El servidor incluye manejo de límite de tasa, pero si alcanzas los límites de la API de Twitter, es posible que debas esperar a que se reinicie la ventana (por ejemplo, 15 minutos para acciones de tweets).

  • Las herramientas de marcadores devuelven 403:

    • get_bookmarks y delete_all_bookmarks requieren TWITTER_OAUTH2_USER_ACCESS_TOKEN. Los tokens de portador solo de aplicación y OAuth 1.0a son rechazados por el endpoint de marcadores.
    • Consulta Obtención de un Token de Usuario OAuth 2.0 para instrucciones de configuración.

  • Advertencias de sintaxis:

    • Si ves mensajes de SyntaxWarning de Tweepy, se deben a problemas de docstrings en Tweepy con Python 3.13. El servidor incluye una supresión de advertencias para manejar esto.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía una solicitud de pull en el repositorio de GitHub.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Autor