Servidor MCP para la API de Twitch

Servidor MCP (Model Context Protocol) que proporciona herramientas para interactuar con la API de Twitch. Permite que asistentes de IA y otras aplicaciones accedan a datos de Twitch de manera estructurada y segura.

🚀 Características

Este servidor MCP proporciona las siguientes herramientas:

📊 Herramientas Disponibles

1. get_twitch_user - Obtiene información detallada de un usuario

   • Entrada: login (nombre de usuario)
   • Devuelve: ID, nombre para mostrar, biografía, imagen de perfil, fecha de creación, etc.

2. check_user_live - Verifica si un usuario está transmitiendo en vivo

   • Entrada: login (nombre de usuario)
   • Devuelve: Datos del stream si está en vivo, null si está offline

3. get_user_videos - Obtiene los videos de un usuario

   • Entrada: login, video_type (archive/highlight/upload/all), limit (1-100)
   • Devuelve: Lista de videos con títulos, duración, vistas, thumbnails, etc.

4. get_top_streams - Obtiene los streams más populares

   • Entrada: game_name (opcional), limit (1-100)
   • Devuelve: Lista de streams con espectadores, títulos, juegos, etc.

5. get_top_games - Obtiene los juegos más populares

   • Entrada: limit (1-100)
   • Devuelve: Lista de juegos con nombre, box art, IDs

6. search_channels - Busca canales por palabras clave

   • Entrada: query, live_only (bool), limit (1-100)
   • Devuelve: Lista de canales coincidentes

7. get_game_info - Obtiene información de un juego

   • Entrada: game_name
   • Devuelve: ID del juego, nombre exacto, box art URL

📋 Requisitos Previos

1. Python 3.10 o superior
2. Credenciales de Twitch API:
   • Ve a https://dev.twitch.tv/console/apps
   • Crea una nueva aplicación
   • Obtén tu Client ID y Client Secret

🔧 Instalación

Método 1: Con UV (Recomendado) ⚡

Paso 1: Instalar UV

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Paso 2: Configurar y ejecutar

cd d:\Workspaces\twitch\mcp
copy .env.example .env
notepad .env  # Agrega tus credenciales

# Ejecutar (UV instalará las dependencias automáticamente)
uv run server.py

Ver QUICKSTART_UV.md para más detalles.

Método 2: Con pip tradicional

Paso 1: Navegar al directorio

cd d:\Workspaces\twitch\mcp

Paso 2: Instalar dependencias

pip install -r requirements.txt

Paso 3: Configurar credenciales

copy .env.example .env
notepad .env  # Agrega tus credenciales

Método 3: Contenedor Docker 🐳

Paso 1: Crear tu archivo de variables de entorno (se reutiliza fuera del contenedor)

cd d:\Workspaces\twitch\mcp
copy .env.example .env
notepad .env  # Agrega tus credenciales de Twitch

Paso 2: Construir la imagen

docker build -t twitch-mcp .

Paso 3: Ejecutar el contenedor en modo SSE (puedes reutilizar el mismo .env)

docker run --rm --name twitch-mcp --env-file .env -p 8000:8000 twitch-mcp

Usa `--host 0.0.0.0` dentro del contenedor para exponer el servidor. El CMD por defecto ya incluye ese valor.

Personalizar host/puerto:

docker run --rm --name twitch-mcp --env-file .env -p 9000:9000 twitch-mcp python server.py --mode sse --host 0.0.0.0 --port 9000

Modo stdio desde Docker: El modo stdio requiere interactuar con stdin/stdout del contenedor. Puedes lanzar:

docker run --rm --name twitch-mcp-stdio --env-file .env -i twitch-mcp python server.py --mode stdio

Ten en cuenta que la mayoría de clientes MCP esperan ejecutar el binario directamente en tu máquina, por lo que este modo desde Docker suele usarse solo para pruebas puntuales.

Método 4: Docker Compose ⚙️

Ideal para dejar el servidor corriendo en segundo plano y reiniciarlo automáticamente si se cae.

Paso 1: Asegúrate de tener tu .env listo (mismo que en el método Docker).

Paso 2: Levanta el servicio y construye la imagen (solo la primera vez o cuando cambies el código):

docker compose up --build

El servicio quedará escuchando en http://localhost:8000/sse.

Ejecutar en segundo plano:

docker compose up -d

Detener:

docker compose down

Sobrescribir parámetros (por ejemplo, otro puerto):

docker compose run --rm -p 9000:9000 twitch-mcp python server.py --mode sse --host 0.0.0.0 --port 9000

El archivo docker-compose.yml mapea el puerto 8000 por defecto y reutiliza el .env para tus credenciales.

Despliegue continuo con GitHub Actions 🚀

Se incluyó un workflow en .github/workflows/deploy-mcp.yml que sincroniza la carpeta mcp con tu VPS y ejecuta docker compose up -d --build automáticamente cuando haces push a master.

1. En tu repositorio de GitHub crea los siguientes Secrets (Settings → Secrets and variables → Actions):

• VPS_HOST: IP o dominio de tu VPS.
• VPS_PORT: Puerto SSH (usa 22 si es el predeterminado).
• VPS_USER: Usuario con permisos para ejecutar Docker.
• VPS_SSH_KEY: Clave privada en formato PEM autorizada en la VPS (sin passphrase).
• VPS_APP_PATH: Ruta absoluta en la VPS donde se copiará el proyecto (ej. /opt/twitch).

2. Asegúrate de que en el VPS exista el archivo mcp/.env con tus credenciales antes del primer despliegue (se preserva entre despliegues).
3. Ejecuta docker compose up -d manualmente la primera vez si quieres validar que todo funciona.

El workflow también puede iniciarse manualmente desde la pestaña Actions (evento workflow_dispatch).

🎯 Uso

Modo 1: STDIO (para clientes MCP como Claude Desktop)

Con UV:

uv run server.py
# O usa el script de inicio
.\run.bat

Con Python tradicional:

python server.py

Modo 2: SSE (para desarrollo y testing)

El modo SSE permite conectarte al servidor desde un navegador o herramientas de testing como MCP Inspector.

Con UV:

# Ejecutar en modo SSE (puerto 8000 por defecto)
uv run server.py --mode sse

# O usa el script de inicio
.\run-sse.bat

# Personalizar host y puerto
uv run server.py --mode sse --host 0.0.0.0 --port 3000

Con Python tradicional:

python server.py --mode sse

Una vez iniciado, verás algo como:

🚀 Servidor MCP de Twitch en modo SSE
📡 Escuchando en http://localhost:8000
🔗 Endpoint SSE: http://localhost:8000/sse
📨 Endpoint Messages: http://localhost:8000/messages

💡 Tip: Usa MCP Inspector para conectarte:
   npx @modelcontextprotocol/inspector http://localhost:8000/sse

Autenticación OAuth en modo SSE

• El servidor implementa OAuth 2.1 con grant type client_credentials y registro dinámico de clientes (RFC 7591).
• Los metadatos se exponen en /.well-known/oauth-authorization-server tal como indica la especificación MCP 2025-03-26.
• Clientes (por ejemplo, ChatGPT connectors) pueden registrarse automáticamente enviando un POST /register con redirect_uris.
• Para obtener tokens, envía un POST /token con grant_type=client_credentials, client_id y client_secret (método client_secret_post).
• Los tokens emitidos deben enviarse como Authorization: Bearer <token> en todas las llamadas a /sse y /messages.
• Personaliza la URL pública con MCP_PUBLIC_BASE_URL si expones el servidor detrás de un proxy o dominio distinto.

Testear con MCP Inspector

# Instalar MCP Inspector (si no lo tienes)
npm install -g @modelcontextprotocol/inspector

# Conectarse al servidor SSE
npx @modelcontextprotocol/inspector http://localhost:8000/sse

Configurar en Claude Desktop (o cualquier cliente MCP)

Ver guía completa: CLAUDE_SETUP.md 📖

Resumen rápido - Con UV (Recomendado) - Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "twitch": {
      "command": "uv",
      "args": [
        "--directory",
        "d:\\Workspaces\\twitch\\mcp",
        "run",
        "server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}

Con Python tradicional - Windows:

{
  "mcpServers": {
    "twitch": {
      "command": "python",
      "args": [
        "d:\\Workspaces\\twitch\\mcp\\server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}

macOS/Linux (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "twitch": {
      "command": "uv",
      "args": [
        "--directory",
        "/ruta/absoluta/a/twitch/mcp",
        "run",
        "server.py"
      ],
      "env": {
        "TWITCH_CLIENT_ID": "tu_client_id_aqui",
        "TWITCH_CLIENT_SECRET": "tu_client_secret_aqui"
      }
    }
  }
}

💡 Ejemplos de Uso

Una vez configurado el servidor en tu cliente MCP, puedes hacer preguntas como:

• "¿Está a_robertdev en vivo en Twitch?"
• "Dame los últimos 10 videos de shroud"
• "¿Cuáles son los 5 juegos más populares en Twitch ahora?"
• "Busca canales que transmitan Minecraft"
• "Dame información del usuario ninja"

🏗️ Arquitectura

mcp/
├── server.py              # Servidor MCP principal (soporta stdio y SSE)
├── twitch_client.py       # Cliente de Twitch API con OAuth y rate limiting
├── pyproject.toml         # Configuración del proyecto para UV
├── requirements.txt       # Dependencias de Python (pip)
├── .env.example           # Plantilla de configuración
├── .gitignore            # Archivos ignorados por git
├── run.bat               # Script de inicio para Windows (stdio)
├── run.sh                # Script de inicio para macOS/Linux (stdio)
├── run-sse.bat           # Script de inicio para Windows (SSE)
├── run-sse.sh            # Script de inicio para macOS/Linux (SSE)
├── README.md             # Este archivo
├── QUICKSTART_UV.md      # Guía rápida para UV
├── SSE_GUIDE.md          # Guía completa del modo SSE
└── EXAMPLES.md           # Ejemplos de uso prácticos

Características del Cliente Twitch

• ✅ OAuth automático - Manejo de tokens con renovación automática
• ✅ Rate limiting - Detecta y maneja límites de tasa (800 req/min)
• ✅ Paginación - Soporte automático para resultados paginados
• ✅ Manejo de errores - Respuestas estructuradas con información útil
• ✅ Cache de tokens - Tokens válidos se reutilizan durante ~1 hora

🔒 Seguridad

• Nunca commitees tu archivo .env o expongas tus credenciales
• El archivo .env está en .gitignore por defecto
• Las credenciales se pasan como variables de entorno, no se guardan en código

🛠️ Desarrollo

Agregar nuevas herramientas

1. Define la herramienta en handle_list_tools() con su schema JSON
2. Implementa la lógica en handle_call_tool()
3. Si necesitas un nuevo endpoint de Twitch, agrégalo en twitch_client.py

Debugging

El servidor imprime mensajes de diagnóstico en stderr:

✅ Twitch API inicializada correctamente

Si hay errores de credenciales:

❌ Error al inicializar Twitch API: ...
💡 Verifica que TWITCH_CLIENT_ID y TWITCH_CLIENT_SECRET estén configurados

📚 Recursos

• QUICKSTART_UV.md - Guía rápida para usar UV
• SSE_GUIDE.md - Guía completa del modo SSE para desarrollo
• EXAMPLES.md - Ejemplos prácticos de uso
• Twitch API Documentation
• Model Context Protocol Docs
• MCP Python SDK
• UV Documentation

🤝 Contribuciones

Este servidor es parte del proyecto Twitch API Integration. Para mejoras o reportar bugs, consulta el repositorio principal.

📝 Licencia

Parte del proyecto Twitch API Integration - Uso educativo y personal.

---

¡Disfruta integrando Twitch con tus asistentes de IA! 🎮🤖