X (Twitter) MCP server

Servidor MCP de X (Twitter)

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con Twitter (X) mediante herramientas de IA. Este servidor permite obtener y publicar tuits, buscar en Twitter, gestionar seguidores y mucho más, todo mediante comandos de lenguaje natural en herramientas de IA.

Características

• Obtenga perfiles de usuarios, seguidores y listas de seguidos.
• Publicar, eliminar y marcar como favoritos tweets.
• Busca tweets y tendencias en Twitter.
• Administrar marcadores y líneas de tiempo.
• Manejo de límite de velocidad integrado para la API de Twitter.
• Utiliza la API de Twitter v2 con la autenticación adecuada (claves API y tokens), evitando el hackeo de nombre de usuario y contraseña para minimizar el riesgo de suspensiones de cuentas.
• Proporciona una implementación completa de los puntos finales de la API de Twitter v2 para la gestión de usuarios, la gestión de tweets, las cronologías y la funcionalidad de búsqueda.

Prerrequisitos

• Python 3.10 o superior : asegúrese de que Python esté instalado en su sistema.
• Cuenta de desarrollador de Twitter : necesita credenciales de API (clave de API, secreto de API, token de acceso, secreto del token de acceso y token de portador) del Portal para desarrolladores de Twitter .
• Opcional: Claude Desktop : descargue e instale la aplicación Claude Desktop desde el sitio web de Anthropic .
• Opcional: Node.js (para la integración de MCP): necesario para ejecutar servidores MCP en Claude Desktop.
• Un administrador de paquetes como uv o pip para dependencias de Python.

Instalación

Opción 1: Instalación mediante herrería (recomendada)

Para instalar automáticamente el servidor X (Twitter) MCP para Claude Desktop a través de Smithery :

Opción 2: Instalar desde PyPI

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

Opción 3: Instalar desde la fuente

Si prefiere instalar desde el repositorio de origen:

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 :
   • Cree un archivo .env en la raíz del proyecto (puede copiar .env.example si se proporciona).
   • Añade tus credenciales de 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

Ejecución del servidor

Puedes ejecutar el servidor de dos maneras:

Opción 1: Uso del script CLI

El proyecto define un script CLI x-twitter-mcp-server .

Si se instala desde PyPI:

Si se instala desde la fuente con uv :

Opción 2: Usar FastMCP directamente (solo fuente)

Si instaló desde la fuente y prefiere ejecutar el servidor utilizando el modo de desarrollo de FastMCP:

El servidor se iniciará y escuchará las conexiones MCP. Debería ver un resultado como este:

Uso con Claude Desktop

Para usar este servidor MCP con Claude Desktop, debe configurar Claude para que se conecte al servidor. Siga estos pasos:

Paso 1: Instalar Node.js

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

• Descargue e instale Node.js desde nodejs.org .
• Verificar la instalación:
  node --version

Paso 2: Localice la configuración del escritorio de Claude

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

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

Si el archivo no existe, créelo.

Paso 3: Configurar el servidor MCP

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

Si se instala desde PyPI:

Si se instala desde la fuente con uv :

• "command": "x-twitter-mcp-server" : utiliza el script CLI directamente si se instala desde PyPI.
• "env" : Si se instala desde PyPI, es posible que deba proporcionar variables de entorno directamente en la configuración (ya que no existe un archivo .env ). Si se instala desde el código fuente, se usará el archivo .env .
• "env": {"PYTHONUNBUFFERED": "1"} : garantiza que la salida no esté almacenada en búfer para un mejor registro en Claude.

Paso 4: Reiniciar Claude Desktop

• Salga de Claude Desktop por completo.
• Vuelva a abrir Claude Desktop para cargar la nueva configuración.

Paso 5: Verificar la conexión

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

Paso 6: Prueba 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á tweets relevantes.
• Obtener tendencias :
  What are the current trending topics on Twitter?
  Claude utilizará la herramienta get_trends para buscar temas en tendencia.

Cuando se le solicite, conceda a Claude permiso para utilizar las herramientas de MCP para la sesión de chat.

Herramientas disponibles

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

Herramientas de gestión de usuarios

get_user_profile

• Descripción : Obtenga información detallada del perfil de un usuario.
• Ejemplo de escritorio de Claude :
  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 : Busca un usuario por nombre de pantalla.
• Ejemplo de escritorio de Claude :
  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 de escritorio de Claude :
  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 de escritorio de Claude :
  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 dado está siguiendo.
• Ejemplo de escritorio de Claude :
  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 de escritorio de Claude :
  Get common followers for user ID 123456789, limit to 50.
  Claude devolverá una lista de hasta 50 seguidores comunes (simulado mediante el filtrado de seguidores).

get_user_subscriptions

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

Herramientas de gestión de tweets

post_tweet

• Descripción : Publica un tweet con contenido multimedia, respuestas y etiquetas opcionales.
• Ejemplo de escritorio de Claude :
  Post a tweet saying "Hello from Claude Desktop! #MCP"
  Claude publicará el tweet y devolverá los detalles del mismo.

delete_tweet

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

get_tweet_details

• Descripción : Obtenga información detallada sobre un tweet específico.
• Ejemplo de escritorio de Claude :
  Get details for tweet ID 123456789012345678.
  Claude devolverá los detalles del tweet, incluido el ID, el texto, la fecha de creación y el ID del autor.

create_poll_tweet

• Descripción : Crea un tweet con una encuesta.
• Ejemplo de escritorio de Claude :
  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 la encuesta y devolverá los detalles del tweet.

vote_on_poll

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

favorite_tweet

• Descripción : Añade un tweet a favoritos.
• Ejemplo de escritorio de Claude :
  Like the tweet with ID 123456789012345678.
  Claude marcará el tweet como favorito y confirmará la acción.

unfavorite_tweet

• Descripción : Quita un tweet de favoritos.
• Ejemplo de escritorio de Claude :
  Unlike the tweet with ID 123456789012345678.
  Claude desmarcará el tweet de favoritos y confirmará la acción.

bookmark_tweet

• Descripción : Agrega el tweet a marcadores.
• Ejemplo de escritorio de Claude :
  Bookmark the tweet with ID 123456789012345678.
  Claude marcará el tweet como favorito y confirmará la acción.

delete_bookmark

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

delete_all_bookmarks

• Descripción : Elimina todos los marcadores.
• Ejemplo de escritorio de Claude :
  Delete all my Twitter bookmarks.
  Claude eliminará todos los marcadores y confirmará la acción.

Cronología y herramientas de búsqueda

get_timeline

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

get_latest_timeline

• Descripción : Obtén tweets de tu cronología de inicio (Siguiendo).
• Ejemplo de escritorio de Claude :
  Show my Twitter Following timeline, limit to 20 tweets.
  Claude te devolverá hasta 20 tweets de tu cronología de seguidores.

search_twitter

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

get_trends

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

get_highlights_tweets

• Descripción : Recupera tweets destacados de la línea de tiempo de un usuario.
• Ejemplo de escritorio de Claude :
  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 : Obtenga tweets que mencionen a un usuario específico.
• Ejemplo de escritorio de Claude :
  Get tweets mentioning user ID 123456789, limit to 20.
  Claude devolverá hasta 20 tweets que mencionen al usuario.

Solución de problemas

• El servidor no se inicia :
  • Asegúrese de que su archivo .env tenga todas las credenciales de API de Twitter requeridas (si se instala desde la fuente).
  • Si se instala desde PyPI, asegúrese de que las variables de entorno estén configuradas en claude_desktop_config.json o en su shell.
  • Verifique la salida del terminal para detectar errores al ejecutar x-twitter-mcp-server .
  • Verifique que uv o su ejecutable de Python estén correctamente instalados y accesibles.
• Claude no detecta el servidor :
  • Confirme que la ruta en claude_desktop_config.json sea correcta.
  • Asegúrese de que el command y args apunten al ejecutable y script correctos.
  • Reinicie Claude Desktop después de actualizar el archivo de configuración.
  • Consulte los registros del modo de desarrollador de Claude (Ayuda → Habilitar modo de desarrollador → Abrir archivo de registro de MCP) para ver si hay errores.
• Errores de límite de velocidad :
  • El servidor incluye el manejo de límites de velocidad, pero si alcanzas los límites de la API de Twitter, es posible que tengas que esperar la ventana de reinicio (por ejemplo, 15 minutos para acciones de tweets).
• Advertencias de sintaxis :
  • Si ve mensajes SyntaxWarning de Tweepy, se debe a problemas con las cadenas de documentación en Tweepy con Python 3.13. El servidor incluye una supresión de advertencias para solucionar esto.

Contribuyendo

¡Agradecemos sus contribuciones! Abra un problema o envíe una solicitud de incorporación de cambios en el repositorio de GitHub .

Licencia

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

Autor

• Rafal Janicki - rafal@kult.io