X (Twitter)

Servidor MCP de X (Twitter)

Una implementación completa de servidor Model Context Protocol para la integración con la API de X (Twitter), con automatización profesional de flujos de trabajo, manejo mejorado de errores y documentación en tiempo real.

🚀 Características

• 53 Herramientas en Total - 33 de la API de Twitter + 20 capacidades mejoradas de investigación de SocialData.tools
• Analítica Avanzada - Análisis de hilos, mapeo de redes, análisis de sentimiento, seguimiento viral
• Supera Restricciones de API - Las herramientas de investigación mejoradas funcionan sin requisitos de nivel Pro
• Manejo Profesional de Errores - Guía clara de actualización y gestión elegante de claves API
• 5 Indicaciones de Flujo de Trabajo - Plantillas de automatización preconstruidas
• 6 Recursos Dinámicos - Documentación de API y estado en tiempo real
• Cumplimiento Total de MCP - Compatibilidad con herramientas, indicaciones y recursos

📋 Inicio Rápido

Requisitos Previos

• Node.js 18+
• npm o yarn
• Credenciales de la API de X (Twitter) (nivel Basic mínimo - $200/mes)

Instalación Local

1. Clonar e Instalar

   git clone <repository-url>
   cd twitter-server
   npm install
   

2. Configuración del Entorno

   cp .env.example .env
   # Edit .env with your credentials
   

   Variables de Entorno Requeridas:

   # Twitter API credentials (Required)
   X_API_KEY=your_api_key_here
   X_API_SECRET=your_api_secret_here  
   X_ACCESS_TOKEN=your_access_token_here
   X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   
   # SocialData.tools API key (Optional - enables enhanced research tools)
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # Optional, uses default if not set
   

3. Compilar y Ejecutar

   npm run build
   npm start
   

4. Probar el Servidor

   # Test with JSON-RPC calls
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # Test specific tool
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js
   

🔑 Configuración de la API de X (Twitter)

Credenciales Requeridas

Añade estas a tu archivo .env:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

Niveles de Acceso a la API

Nivel	Costo	Herramientas Funcionando	Herramientas Limitadas
Basic	$200/mes	18/22 herramientas	searchTweets, getHashtagAnalytics
Pro	$5,000/mes	Las 22 herramientas	Ninguna

🛠️ Herramientas Disponibles (53 en Total)

🐦 Herramientas de la API de Twitter (33 herramientas)

✅ Operaciones de Tweets (Todas Funcionando)

• postTweet - Publicar nuevos tweets
• getTweetById - Obtener tweets específicos
• replyToTweet - Responder a tweets
• deleteTweet - Eliminar tus tweets

✅ Interacción (Todas Funcionando)

• likeTweet / unlikeTweet - Dar me gusta/quitar me gusta a tweets
• retweet / undoRetweet - Retwittear/deshacer retweets
• getRetweets - Obtener usuarios que retwitearon

✅ Gestión de Usuarios (La Mayoría Funcionando)

• getUserInfo - Obtener perfiles de usuario ✅
• getUserTimeline - Obtener tweets de usuario ✅
• followUser / unfollowUser - Seguir/dejar de seguir usuarios ✅
• getFollowers - Obtener seguidores ⚠️ (403 - requiere permisos especiales)
• getFollowing - Obtener seguidos ⚠️ (403 - requiere permisos especiales)

✅ Gestión de Listas (Todas Funcionando)

• createList - Crear listas de X (Twitter)
• getUserLists - Obtener las listas del usuario
• addUserToList / removeUserFromList - Gestionar miembros de listas
• getListMembers - Obtener miembros de listas

⚠️ Búsqueda y Analítica (Limitadas)

• searchTweets - Buscar tweets (requiere nivel Pro - $5,000/mes)
• getHashtagAnalytics - Analítica de hashtags (requiere nivel Pro)
• getLikedTweets - Obtener tweets con me gusta (problema de acceso a la API)

🔍 Investigación Mejorada de SocialData.tools (20 herramientas)

Nota: Estas herramientas gestionan elegantemente las claves API faltantes con instrucciones de configuración útiles

🔎 Búsqueda Avanzada (6 herramientas)

• advancedTweetSearch - Consultas complejas con operadores, supera las restricciones de nivel de API
• historicalTweetSearch - Acceso a tweets históricos más allá de los límites estándar de la API
• trendingTopicsSearch - Análisis de tendencias en tiempo real y descubrimiento de contenido popular
• bulkUserProfiles - Análisis de perfiles multiusuario en solicitudes únicas
• userGrowthAnalytics - Análisis de patrones de crecimiento de usuarios a lo largo del tiempo
• userInfluenceMetrics - Puntuación de interacción y cálculos de influencia

🧵 Análisis de Hilos y Conversaciones (3 herramientas)

• getFullThread - Reconstruir hilos completos de Twitter con métricas de interacción
• getConversationTree - Mapear la estructura de la conversación, incluyendo respuestas y citas
• getThreadMetrics - Análisis de rendimiento de hilos y distribución de interacción

🌐 Análisis de Redes (3 herramientas)

• findMutualConnections - Descubrir conexiones mutuas mediante interacciones
• analyzeFollowerDemographics - Patrones de seguidores y análisis demográfico
• mapInfluenceNetwork - Mapeo de influencia y análisis de fuerza de conexión

📈 Analítica Avanzada (3 herramientas)

• getHashtagTrends - Seguimiento del rendimiento de hashtags a lo largo del tiempo con análisis de tendencias
• analyzeSentiment - Análisis de sentimiento con seguimiento de frecuencia de palabras clave
• trackVirality - Patrones de propagación viral y análisis de velocidad de interacción

📱 Mensajes Directos y Moderación (5 herramientas)

• Varias herramientas de DM y moderación de usuarios

🔑 Configuración de Claves API

Twitter API (Requerida)

Obtén estas desde el Portal de Desarrolladores de Twitter:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

API de SocialData.tools (Opcional)

Habilita 20 herramientas de investigación mejoradas que superan las limitaciones de la API de Twitter:

1. Regístrate en SocialData.tools
2. Obtén tu clave API desde el panel de control
3. Añade al archivo .env:

   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   

Sin la clave API de SocialData: Las herramientas de investigación mejoradas mostrarán instrucciones de configuración útiles en lugar de errores.

🧪 Probando la Integración con SocialData.tools

Probar Herramientas de Investigación Mejoradas

# Test advanced tweet search (bypasses Twitter API Pro tier requirement)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "AI OR machine learning", "maxResults": 5}}}' | node dist/index.js

# Test sentiment analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

# Test user influence metrics
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "userInfluenceMetrics", "arguments": {"username": "openai"}}}' | node dist/index.js

# Test thread analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

Probar Sin Clave API

# These will show helpful setup instructions instead of errors
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

🆚 Cuándo Usar Cada Herramienta

Comparación entre Twitter API y SocialData.tools

Caso de Uso	Herramienta de Twitter API	Alternativa de SocialData.tools	Ventaja
Búsqueda Básica	searchTweets ⚠️ (nivel Pro $5k/mes)	advancedTweetSearch ✅	Supera las restricciones de API
Análisis de Usuarios	getUserInfo ✅	userInfluenceMetrics ✅	Analítica mejorada
Datos Históricos	Limitado por el nivel de API	historicalTweetSearch ✅	Acceso a tweets más antiguos
Análisis de Sentimiento	No disponible	analyzeSentiment ✅	Puntuación de sentimiento integrada
Análisis de Hilos	Reconstrucción manual	getFullThread ✅	Mapeo automatizado de hilos
Mapeo de Redes	No disponible	mapInfluenceNetwork ✅	Análisis de conexiones
Tendencias de Hashtags	getHashtagAnalytics ⚠️ (nivel Pro)	getHashtagTrends ✅	Sin restricciones de nivel

Flujo de Trabajo Recomendado

1. Comienza con las herramientas de Twitter API para publicar, interactuar y operaciones básicas
2. Usa SocialData.tools para investigación, analítica e información avanzada
3. Combina ambos para automatización y análisis integral de Twitter

🎯 Indicaciones de Flujo de Trabajo MCP

Nuestro servidor incluye 5 plantillas profesionales de flujo de trabajo:

1. Composición de Tweets (compose-tweet)

Guía interactiva para crear tweets atractivos con hashtags, menciones y medios.

2. Informes de Analítica (analytics-report)

Flujo de trabajo integral de analítica de X (Twitter) para información empresarial.

3. Estrategia de Contenido (content-strategy)

Planificación estratégica de contenido y flujos de trabajo de interacción con la audiencia.

4. Gestión de Comunidad (community-management)

Mejores prácticas de servicio al cliente e interacción con la comunidad.

5. Investigación de Hashtags (hashtag-research)

Investigación de hashtags específicos de la industria y análisis de tendencias.

📊 Recursos Dinámicos

Información en tiempo real accesible mediante MCP:

• Límites de Tasa de API - Monitoreo de uso en vivo
• Estado del Nivel de Acceso - Capacidades actuales del nivel
• Informe de Estado de Herramientas - Herramientas funcionando vs. limitadas
• Guía de Inicio Rápido - Documentación para comenzar
• Plantillas de Flujo de Trabajo - Ejemplos de automatización preconstruidos
• Datos de Perfil de Usuario - Información dinámica de usuarios (llamadas de API en vivo)

🧪 Pruebas

Pruebas Manuales

# Test working tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Test limited tools (will show upgrade guidance)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

Resumen de Resultados de Pruebas

• 18 Herramientas Funcionando en el nivel Basic
• 4 Herramientas Limitadas por nivel/per permisos de API
• Mensajes de error profesionales con guía de actualización
• Toda la funcionalidad principal operativa

🔧 Ejemplos de Integración

Cliente MCP (Cursor/Claude)

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/twitter-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret", 
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

JSON-RPC Directo

# Always source environment first
source .env

# List all tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call specific tool
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

📝 Documentación de la API

Operaciones de Tweets

postTweet

{
  "text": "Your tweet content (up to 280 characters)"
}

getTweetById

{
  "tweetId": "1234567890123456789",
  "tweetFields": ["created_at", "public_metrics", "author_id"]
}

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "Your reply content"
}

Operaciones de Usuario

getUserInfo

{
  "username": "elonmusk",
  "fields": ["description", "public_metrics", "profile_image_url"]
}

followUser

{
  "username": "target_username"
}

Interacción

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 Manejo de Errores

Mensajes de Error Profesionales

Nuestro manejo mejorado de errores proporciona:

• Explicaciones claras del nivel de API para herramientas limitadas
• Información de precios de actualización ($5,000/mes nivel Pro)
• Enlaces directos de actualización al Portal de Desarrolladores de Twitter
• Sugerencias de soluciones alternativas

Ejemplo de respuesta de error:

{
  "error": "This endpoint requires X (Twitter) API Pro tier access ($5,000/month). Visit https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve to upgrade your access level."
}

📁 Estructura del Proyecto

twitter-server/
├── src/
│   ├── handlers/          # API endpoint handlers
│   ├── prompts.ts        # MCP workflow prompts  
│   ├── resources.ts      # Dynamic MCP resources
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled JavaScript
├── scripts/              # Documentation & PRD
└── package.json

🔄 Desarrollo

Compilar y Ejecutar

npm run build    # Compile TypeScript
npm start        # Start production server
npm run dev      # Development mode with watch

Añadir Nuevas Herramientas

1. Añade la función de manejo en el archivo src/handlers/ apropiado
2. Registra la herramienta en src/index.ts
3. Añade la documentación a este README
4. Prueba con llamadas JSON-RPC

Contribuir

1. Sigue los patrones de código existentes
2. Añade un manejo de errores adecuado con mensajes profesionales
3. Prueba tanto con escenarios de éxito como de fallo
4. Actualiza la documentación

📋 Limitaciones Conocidas

Restricciones de Nivel de API

• searchTweets: Requiere nivel Pro ($5,000/mes)
• getHashtagAnalytics: Requiere nivel Pro
• getFollowers/getFollowing: Requiere permisos especiales (errores 403)
• getLikedTweets: Problemas de validación de parámetros

Recomendaciones

• Configuración Actual: Excelente para automatización básica de X (Twitter)
• Para Analítica Avanzada: Considera la actualización al nivel Pro
• Para Seguidores/Seguidos: Solicita permisos elevados

🆘 Solución de Problemas

Problemas Comunes

Error: "fetch is not defined"

# Ensure Node.js 18+ 
node --version

Errores de Permiso 403

• Verifica que las credenciales de la API sean correctas
• Confirma que la cuenta tenga los permisos requeridos
• Algunos endpoints necesitan aprobación especial

Errores de Solicitud Incorrecta 400

• Revisa los formatos de los parámetros
• Consulta nuestros mensajes de error mejorados para obtener orientación
• Verifica que el nivel de API sea compatible con el endpoint

Obtener Ayuda

1. Revisa los mensajes de error - Nuestro manejo mejorado de errores proporciona orientación clara
2. Consulta la documentación de la API - Portal de Desarrolladores de X (Twitter)
3. Primero prueba con herramientas funcionales - Verifica la configuración básica
4. Revisa las variables de entorno - Asegúrate de que todas las credenciales estén establecidas

---

📊 Estado Actual

• 53 Herramientas en Total: 33 de Twitter API + 20 de investigación mejorada de SocialData.tools
• Analítica Avanzada: Análisis de hilos, mapeo de redes, análisis de sentimiento, seguimiento viral
• Manejo Elegante de Claves API: Las herramientas mejoradas muestran instrucciones de configuración útiles cuando falta la clave API
• Supera Restricciones de API: Las herramientas de investigación funcionan sin requisitos de nivel Pro de Twitter
• Manejo Profesional de Errores: Guía clara de actualización y mensajes fáciles de usar
• Cumplimiento Total de MCP: Herramientas, indicaciones y recursos
• Listo para Producción: Fiabilidad mejorada, analítica integral y excelente experiencia de usuario

Hecho con ❤️ usando el Model Context Protocol y la integración con SocialData.tools