agente-cliente-twitter-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) que se integra con Twitter mediante el paquete agent-twitter-client , lo que permite que los modelos de IA interactúen con Twitter sin acceso directo a la API.

Características

Opciones de autenticación :
- Autenticación basada en cookies (recomendada)
- Autenticación de nombre de usuario/contraseña
- Credenciales de la API de Twitter v2
Operaciones de Tweet :
- Obtener tweets de los usuarios
- Obtener tweets específicos por ID
- Buscar tweets
- Envía tweets con texto y multimedia
- Crear encuestas
- Dar me gusta, retuitear y citar tuits
Operaciones de usuario :
- Obtener perfiles de usuario
- Seguir a los usuarios
- Consigue seguidores y listas de seguidores
Integración de Grok :
- Chatea con Grok a través de la interfaz de Twitter
- Continuar conversaciones con identificadores de conversación
- Obtener resultados de búsqueda web y citas
- Accede a los datos en tiempo real de Twitter a través de Grok
- Nota : La funcionalidad de Grok requiere agent-twitter-client v0.0.19 o superior

Documentación

Guía para desarrolladores : guía completa para desarrolladores
Guía de pruebas : instrucciones para probar el MCP
Guía del agente : Guía para agentes de IA sobre cómo usar el MCP de Twitter
Guía de contribución : Pautas para contribuir a este proyecto
Registro de cambios : historial de cambios en este proyecto
README de demostración : Guía para ejecutar los scripts de demostración
Ejemplos de Grok : documentación para los ejemplos de integración de Grok AI

Inicio rápido

Instalación

# Install globally
npm install -g agent-twitter-client-mcp

# Or install locally
npm install agent-twitter-client-mcp

Uso básico

Crea un archivo .env con tus credenciales de Twitter (ver Métodos de autenticación )
Ejecute el servidor MCP:

# If installed globally
agent-twitter-client-mcp

# If installed locally
npx agent-twitter-client-mcp

Scripts de demostración

El paquete incluye un directorio demo con scripts de ejemplo que demuestran varias funciones:

# Clone the repository to access the demo scripts
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# Run the interactive demo menu
./run-demo.sh

# Run a specific demo script
./run-demo.sh --script tweet-search.js

# Run Grok AI examples (requires agent-twitter-client v0.0.19)
./run-demo.sh --script simple-grok.js --use-local-agent-twitter-client
./run-demo.sh --script grok-chat.js --use-local-agent-twitter-client

Consulte el archivo README de demostración para obtener más detalles.

Configuración del puerto

De forma predeterminada, el servidor MCP se ejecuta en el puerto 3000. Si necesita cambiar esto (por ejemplo, si ya tiene una aplicación ejecutándose en el puerto 3000), tiene varias opciones:

Opción 1: Uso de variables de entorno

Establezca la variable de entorno PORT :

PORT=3001 npx agent-twitter-client-mcp

Opción 2: Usar Docker Compose

Si usa Docker Compose, puede configurar los puertos del host y del contenedor en su archivo .env :

# .env file
MCP_HOST_PORT=3001    # The port on your host machine
MCP_CONTAINER_PORT=3000  # The port inside the container

Luego ejecuta:

docker-compose up -d

Esto asignará el puerto 3001 de su host al puerto 3000 del contenedor, lo que le permitirá acceder al MCP en http://localhost:3001 mientras su otra aplicación continúa usando el puerto 3000.

Configuración con Claude Desktop

Configure Claude Desktop para usar este MCP agregando a su archivo de configuración:

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

{
  "mcpServers": {
    "agent-twitter-client-mcp": {
      "command": "npx",
      "args": ["-y", "agent-twitter-client-mcp"],
      "env": {
        "AUTH_METHOD": "cookies",
        "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
      }
    }
  }
}

Reiniciar Claude Desktop

Métodos de autenticación

Autenticación mediante cookies (recomendada)

{
  "AUTH_METHOD": "cookies",
  "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
}

Para obtener cookies:

Inicie sesión en Twitter en su navegador
Abrir herramientas para desarrolladores (F12)
Vaya a la pestaña Aplicación > Cookies
Copiar los valores de las cookies auth_token , ct0 y twid
Asegúrese de incluir la parte Domain=.twitter.com para cada cookie

Autenticación de nombre de usuario/contraseña

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "your_email@example.com", // Optional
  "TWITTER_2FA_SECRET": "your_2fa_secret" // Optional, required if 2FA is enabled
}

Autenticación de la API de Twitter

{
  "AUTH_METHOD": "api",
  "TWITTER_API_KEY": "your_api_key",
  "TWITTER_API_SECRET_KEY": "your_api_secret_key",
  "TWITTER_ACCESS_TOKEN": "your_access_token",
  "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}

Herramientas disponibles

get_user_tweets : recupera tweets de un usuario específico
get_tweet_by_id : Obtener un tweet específico por ID
search_tweets : Buscar tweets
send_tweet : Publicar un nuevo tweet
send_tweet_with_poll : Publica un tweet con una encuesta
like_tweet : Me gusta un tweet
retweet : retuitear un tuit
quote_tweet : Citar un tweet
get_user_profile : Obtener el perfil de un usuario
follow_user : Seguir a un usuario
get_followers : Obtener los seguidores de un usuario
get_following : Obtener los usuarios que un usuario está siguiendo
grok_chat : Chatea con Grok a través de Twitter
health_check : Comprueba el estado del servidor MCP de Twitter

Interfaz de prueba

El MCP incluye una interfaz de línea de comandos interactiva para probar:

npx agent-twitter-client-mcp-test
# or if installed locally
npm run test:interface

Esto inicia un REPL donde puedes probar varias funciones MCP:

agent-twitter-client-mcp> help

Available commands:
  health                     Run a health check
  profile <username>         Get a user profile
  tweets <username> [count]  Get tweets from a user
  tweet <id>                 Get a specific tweet by ID
  search <query> [count]     Search for tweets
  post <text>                Post a new tweet
  like <id>                  Like a tweet
  retweet <id>               Retweet a tweet
  quote <id> <text>          Quote a tweet
  follow <username>          Follow a user
  followers <userId> [count] Get a user's followers
  following <userId> [count] Get users a user is following
  grok <message>             Chat with Grok
  help                       Show available commands
  exit                       Exit the test interface

Comandos de prueba de ejemplo

# Run a health check
agent-twitter-client-mcp> health

# Search for tweets
agent-twitter-client-mcp> search mcp 2

# Get a user's profile
agent-twitter-client-mcp> profile elonmusk

# Get tweets from a user
agent-twitter-client-mcp> tweets openai 5

# Chat with Grok
agent-twitter-client-mcp> grok Explain quantum computing in simple terms

Ejemplo de uso

Pídele a Claude que:

Busca tuits sobre IA en Twitter.
Publica un tweet que diga '¡Hola de Claude!'
Recibe los últimos tweets de @OpenAI
Charla con Grok sobre computación cuántica

Uso avanzado

Trabajar con los medios de comunicación

Para publicar un tweet con una imagen:

I want to post a tweet with an image. The tweet should say "Beautiful sunset today!" and include this image.

Para publicar un tweet con un vídeo:

I want to post a tweet with a video. The tweet should say "Check out this amazing video!" and include the video file.

Creación de encuestas

Para crear una encuesta:

Create a Twitter poll asking "What's your favorite programming language?" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.

Interactuando con Grok

Para tener una conversación con Grok:

Use Grok to explain quantum computing to me. Ask it to include some real-world applications.

Para continuar una conversación con Grok:

Continue the Grok conversation and ask it to elaborate on quantum entanglement.

Las capacidades únicas de Grok

Grok en Twitter tiene acceso a datos de Twitter en tiempo real que ni siquiera la API independiente de Grok tiene. Esto significa que puedes preguntarle a Grok sobre:

Temas de tendencia actuales en Twitter
Análisis de tuits recientes sobre temas específicos
Información sobre los usuarios de Twitter y su contenido
Eventos en tiempo real que se discuten en la plataforma

Consultas de ejemplo:

"¿Cuáles son los temas de tendencia en Twitter en este momento?"
Analizar el sentimiento en torno a la IA en Twitter.
"¿Qué dice la gente sobre el último evento de Apple?"
Muéstrame información sobre las memecoins populares que se están discutiendo hoy.

Requisitos de autenticación de Grok

La funcionalidad de Grok requiere una autenticación adecuada. El MCP admite dos métodos:

Autenticación de cookies (recomendado):
- Las cookies deben estar en formato de matriz JSON
- Ejemplo: TWITTER_COOKIES=["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com", "twid=u=YOUR_USER_ID; Domain=.twitter.com"]
- Las cookies esenciales son auth_token , ct0 y twid
Autenticación de nombre de usuario/contraseña :
- Establezca TWITTER_USERNAME y TWITTER_PASSWORD en su entorno
- Es posible que encuentre protección de Cloudflare en algunos casos

Límites de velocidad de Grok

Grok tiene límites de velocidad que pueden afectar el uso:

Cuentas no premium: 25 mensajes cada 2 horas
Cuentas Premium: Límites más altos

El MCP devolverá información sobre el límite de velocidad en la respuesta cuando se alcancen los límites.

Para obtener más detalles sobre el uso de Grok, consulte la documentación de Ejemplos de Grok .

Solución de problemas

Problemas de autenticación

Problemas de autenticación de cookies

Si tiene problemas con la autenticación de cookies:

Caducidad de las cookies : Las cookies de Twitter suelen caducar después de un tiempo determinado. Intenta actualizar tus cookies cerrando sesión y volviendo a iniciar sesión en Twitter.
Formato de las cookies : asegúrese de que sus cookies tengan el formato correcto como una matriz JSON de cadenas con el dominio correcto.
Cookies necesarias : asegúrese de haber incluido las cookies esenciales: auth_token , ct0 y twid .

Ejemplo de cookies con formato correcto:

"TWITTER_COOKIES": "[\"auth_token=1234567890abcdef; Domain=.twitter.com\", \"ct0=abcdef1234567890; Domain=.twitter.com\", \"twid=u%3D1234567890; Domain=.twitter.com\"]"

Problemas de autenticación de credenciales

Si tiene problemas con la autenticación de nombre de usuario y contraseña:

Autenticación de dos factores : si su cuenta tiene habilitada la 2FA, deberá proporcionar TWITTER_2FA_SECRET .
Bloqueos de cuenta : Si intentas iniciar sesión repetidamente, tu cuenta podría bloquearse. Revisa tu correo electrónico para ver si hay solicitudes de verificación.
Desafíos de Captcha : Twitter puede presentar desafíos de captcha que el cliente no puede manejar automáticamente.

Problemas de autenticación de API

Para problemas de autenticación de API:

Permisos de clave API : asegúrese de que sus claves API tengan los permisos necesarios para las acciones que intenta realizar.
Limitación de velocidad : la API de Twitter tiene límites de velocidad que pueden provocar fallas si se exceden.
Cambios de API : Twitter ocasionalmente cambia su API, lo que puede causar problemas de compatibilidad.

Errores de operación

Errores en la publicación de tweets

Si no puedes publicar tweets:

Restricciones de contenido : Twitter puede bloquear tweets que violen sus políticas de contenido.
Problemas de formato de medios : asegúrese de que los medios estén correctamente formateados y codificados.
Limitación de velocidad : Twitter limita la frecuencia con la que puedes publicar.

Problemas de búsqueda

Si la búsqueda no funciona:

Sintaxis de consulta : asegúrese de que su consulta de búsqueda siga la sintaxis de búsqueda de Twitter.
Limitaciones de búsqueda : algunos modos de búsqueda pueden tener restricciones o requerir permisos específicos.

Problemas de Grok

Si la funcionalidad de Grok no funciona:

Requisitos de versión :
- Grok requiere agent-twitter-client v0.0.19 o superior
- El paquete actual utiliza v0.0.18 para la funcionalidad básica
- Para los scripts de demostración, use el indicador --use-local-agent-twitter-client para instalar temporalmente la versión v0.0.19
Problemas de autenticación :
- Formato de las cookies: asegúrese de que las cookies tengan el formato de matriz JSON correcto
- Validez de las cookies: Las cookies de Twitter caducan después de un período determinado
- Protección de Cloudflare: Cloudflare puede bloquear la autenticación de nombre de usuario y contraseña
- Requisito Premium: El acceso a Grok requiere una suscripción a Twitter Premium
Límites de velocidad :
- Cuentas no premium: 25 mensajes cada 2 horas
- Mensaje de error: "Tarifa limitada: has alcanzado el límite..."
- Solución: Espere hasta que se restablezca el límite de velocidad o actualice a una cuenta premium
Ubicación del archivo de entorno :
- Para los scripts de demostración, asegúrese de que sus credenciales estén en demo/.env , no en el archivo raíz .env
- Utilice el indicador --debug-env para comprobar qué variables de entorno se están cargando

Para obtener una solución detallada de problemas de Grok, consulte la documentación de Ejemplos de Grok .

Problemas con el servidor

Chequeo de salud

Utilice la herramienta health_check para diagnosticar problemas del servidor:

Run a health check on the agent-twitter-client-mcp server to diagnose any issues.

El control de salud informará sobre:

Estado de autenticación
Conectividad API
Uso de memoria

Explotación florestal

El servidor registra tanto en la consola como en los archivos:

error.log : contiene mensajes de nivel de error
combined.log : contiene todos los mensajes de registro

Consulte estos registros para obtener información detallada sobre los errores.

Desarrollo

Prerrequisitos

Node.js 18+
npm

Configuración

Clonar el repositorio

git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp

Instalar dependencias

npm install

Cree un archivo .env con la configuración:

AUTH_METHOD=cookies
TWITTER_COOKIES=["cookie1=value1", "cookie2=value2"]

Construir el proyecto

npm run build

Iniciar el servidor

npm start

Variables de entorno

Además de las variables de autenticación, puede configurar:

LOG_LEVEL : establece el nivel de registro (error, advertencia, información, depuración)
NODE_ENV : Establecer entorno (desarrollo, producción)

Estibador

También puedes ejecutar el servidor usando Docker:

Usando Docker directamente

# Build the Docker image
docker build -t agent-twitter-client-mcp .

# Run the container with environment variables
docker run -p 3000:3000 \
  -e AUTH_METHOD=cookies \
  -e TWITTER_COOKIES='["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com"]' \
  agent-twitter-client-mcp

Uso de Docker Compose

Crea un archivo .env con tus credenciales de Twitter
Ejecutar con docker-compose:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Variables de entorno en Docker

Puede pasar variables de entorno al contenedor Docker de varias maneras:

En el archivo docker-compose.yml (ya configurado)
A través de un archivo .env (recomendado para docker-compose)
Directamente en el comando docker run (como se muestra arriba)

Registros persistentes

La configuración de docker-compose incluye un montaje de volumen para registros:

volumes:
  - ./logs:/app/logs

Esto almacenará registros en un directorio de logs en la carpeta de su proyecto.

Consideraciones de seguridad

Almacenamiento de credenciales : almacene las credenciales de forma segura, preferiblemente utilizando variables de entorno o una bóveda segura.
Limitación de velocidad : implemente una limitación de velocidad para evitar el abuso de la API de Twitter.
Validación de contenido : valide todo el contenido antes de publicarlo para evitar usos maliciosos.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Integrations