Provides tools for interacting with the Twitch API, allowing users to retrieve user information, check live status, list videos, get top streams and games, search channels, and fetch game details.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Twitch MCP Server Check if shroud is live"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Este servidor MCP proporciona las siguientes herramientas:
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.
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
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.
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.
get_top_games - Obtiene los juegos más populares
Entrada: limit (1-100)
Devuelve: Lista de juegos con nombre, box art, IDs
search_channels - Busca canales por palabras clave
Entrada: query, live_only (bool), limit (1-100)
Devuelve: Lista de canales coincidentes
get_game_info - Obtiene información de un juego
Entrada: game_name
Devuelve: ID del juego, nombre exacto, box art URL
Related MCP server: twitch-mcp
Python 3.10 o superior
Credenciales de Twitch API:
Crea una nueva aplicación
Obtén tu Client ID y Client Secret
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.pyVer QUICKSTART_UV.md para más detalles.
Paso 1: Navegar al directorio
cd d:\Workspaces\twitch\mcpPaso 2: Instalar dependencias
pip install -r requirements.txtPaso 3: Configurar credenciales
copy .env.example .env
notepad .env # Agrega tus credencialesPaso 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 TwitchPaso 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-mcpUsa
`--host 0.0.0.0`dentro del contenedor para exponer el servidor. ElCMDpor 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 9000Modo 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 stdioTen 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.
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 --buildEl servicio quedará escuchando en http://localhost:8000/sse.
Ejecutar en segundo plano:
docker compose up -dDetener:
docker compose downSobrescribir 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 9000El archivo docker-compose.yml mapea el puerto 8000 por defecto y reutiliza el .env para tus credenciales.
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.
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).
Asegúrate de que en el VPS exista el archivo mcp/.env con tus credenciales antes del primer despliegue (se preserva entre despliegues).
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).
Con UV:
uv run server.py
# O usa el script de inicio
.\run.batCon Python tradicional:
python server.pyEl 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 3000Con Python tradicional:
python server.py --mode sseUna 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/sseEl 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.
# Instalar MCP Inspector (si no lo tienes)
npm install -g @modelcontextprotocol/inspector
# Conectarse al servidor SSE
npx @modelcontextprotocol/inspector http://localhost:8000/sseVer 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"
}
}
}
}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"
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✅ 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
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
Define la herramienta en handle_list_tools() con su schema JSON
Implementa la lógica en handle_call_tool()
Si necesitas un nuevo endpoint de Twitch, agrégalo en twitch_client.py
El servidor imprime mensajes de diagnóstico en stderr:
✅ Twitch API inicializada correctamenteSi hay errores de credenciales:
❌ Error al inicializar Twitch API: ...
💡 Verifica que TWITCH_CLIENT_ID y TWITCH_CLIENT_SECRET estén configuradosQUICKSTART_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
Este servidor es parte del proyecto Twitch API Integration. Para mejoras o reportar bugs, consulta el repositorio principal.
Parte del proyecto Twitch API Integration - Uso educativo y personal.
¡Disfruta integrando Twitch con tus asistentes de IA! 🎮🤖
Verifica si un usuario de Twitch está transmitiendo en vivo actualmente. Devuelve información del stream si está en vivo, o null si está offline.
| Name | Required | Description | Default |
|---|---|---|---|
| login | Yes | Nombre de usuario de Twitch (login name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait: returns stream information if live and null if offline, which is beyond what the schema reveals. It doesn't mention rate limits or error handling, but for a simple status check the core behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, with no wasted words. Every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return behavior (stream information or null), which is necessary because no output schema exists. The single parameter is well-defined. It is complete for a simple status check, though it leaves the exact contents of 'stream information' unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'login' parameter is described as 'Nombre de usuario de Twitch (login name)'). The tool description adds no additional parameter semantics, so it aligns with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Verifica') and clearly identifies the resource (un usuario de Twitch) and the condition being checked (si está transmitiendo en vivo). It distinguishes this tool from sibling tools like get_twitch_user (profile) or get_top_streams (global list) by focusing on a single user's live status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool: to check if a specific Twitch user is currently live, returning null if offline. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of the highest tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene estadísticas de seguidores de un canal incluyendo el total y los seguidores más recientes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número de seguidores recientes a listar (1-100) | |
| login | Yes | Nombre de usuario del canal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the operation is a retrieval ('obtiene') and specifies the output scope (total and recent followers). However, it does not mention authorization requirements or rate limits, but the read-only nature is clear from the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose without redundant detail. Every word contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and complete schema coverage, the description sufficiently covers the core functionality. It could detail the exact response structure more explicitly since no output schema is provided, but the description's mention of 'total' and 'most recent followers' gives a reasonable picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both 'login' and 'limit', so the description adds little parameter-level detail. It does clarify the output includes a total count and a list of recent followers, but this relates to the response rather than the input parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves follower statistics for a channel, specifically the total follower count and most recent followers. This distinguishes it from sibling tools like get_twitch_user or check_user_live, which target different aspects of a channel or user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as get_creator_insights. The description only implies its use case by stating what it does, providing no exclusions or context for when another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Genera un resumen ejecutivo para un creador: estado en vivo, crecimiento de seguidores, VODs y clips recientes.
| Name | Required | Description | Default |
|---|---|---|---|
| login | Yes | Nombre de usuario del creador | |
| vod_limit | No | Cantidad de VODs recientes a incluir (1-20) | |
| clip_limit | No | Cantidad de clips destacados a incluir (1-50) | |
| window_days | No | Ventana de días a analizar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits. It only states the purpose and does not clarify that this is a safe read-only operation, nor does it describe the output format, potential latency from aggregation, or authentication requirements. This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action (generates an executive summary) and lists the included content areas. It is concise with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description should provide more context about the return value and behavior. It mentions the content areas but not the format or how the summary is generated, leaving it partially complete for an aggregation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, only hinting at the summary components without explaining how parameters affect them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates an executive summary for a creator, listing specific content areas (live status, follower growth, recent VODs and clips). This distinguishes it from sibling tools like check_user_live and get_user_clips, which focus on individual data points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for when an aggregated overview is needed, but it does not explicitly say when to use it over siblings or mention exclusions. No alternative tools are referenced, leaving usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene información detallada de un juego en Twitch por su nombre. Devuelve ID, nombre, box art URL.
| Name | Required | Description | Default |
|---|---|---|---|
| game_name | Yes | Nombre del juego a buscar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the return fields (ID, name, box art URL), which is useful, but it doesn't mention any potential errors, rate limits, or confirm that it's a read-only operation beyond the verb 'Obtiene'. The description adds value but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that immediately state what the tool does and what it returns. There is zero filler or redundancy, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter lookup with no output schema, the description provides sufficient information: it names the resource, the lookup method, and the return fields. It could be slightly more complete by explicitly contrasting with get_top_games, but overall it's adequate for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter game_name, with a clear Spanish description. The tool description adds no additional parameter semantics beyond restating that the game is searched by name. The schema does the heavy lifting, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Obtiene'), resource ('información de un juego en Twitch'), and the method ('por su nombre'). It also lists the return fields, distinguishing it from siblings like get_top_games which list games rather than retrieve detail by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for when you have a specific game name, which distinguishes it from get_top_games or other list-oriented tools. However, it doesn't explicitly state exclusions or name alternative tools, so it's clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene los juegos más populares en Twitch actualmente, ordenados por número de espectadores.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número máximo de juegos a devolver (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears responsibility for disclosing behavior. It discloses that the list is sorted by viewer count and current, but does not describe the return format, authentication needs, or rate limits. This is a read-only operation, so risk is low, but additional context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear, declarative sentence with no fluff. It front-loads the verb and subject.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list retrieval with one optional parameter. The description covers the core behavior (what, where, sorting). Since there is no output schema, the return structure is not detailed, but that's not a major gap for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter 'limit' with default, min, max, and a Spanish description. The tool description adds no extra parameter detail beyond the schema, but the baseline for high schema coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the most popular Twitch games sorted by viewer count, using specific verb 'Obtiene' and resource 'juegos más populares en Twitch'. It distinguishes from sibling tools like get_top_streams (streams vs games) and get_game_info (list vs specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a ranked list of the most popular games currently on Twitch. It does not explicitly name alternative tools or exclusion criteria, but the scope is clear enough to separate it from top streams and game-specific info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene los streams más populares en Twitch actualmente. Puede filtrar por juego y limitar resultados.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número máximo de streams a devolver (1-100) | |
| game_name | No | Nombre del juego para filtrar streams (opcional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only indicates a read operation ('obtiene') and that results reflect current popularity, but it does not mention return format, pagination limits, default sorting, rate limits, or what happens when no parameters are provided. This is a significant gap for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the primary function first, then mentions the two optional capabilities. It contains no redundant wording and is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core purpose is clear, the description lacks guidance on when to use the tool, what the returned data looks like (since there is no output schema), and behavioral details. For a simple 2-parameter tool, this is minimal but leaves an agent uncertain about expected return values and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'limit' and 'game_name' have clear descriptions in the schema. The tool description adds only a brief reference to 'filtrar por juego y limitar resultados,' which partly mirrors the schema but does not provide extra meaning beyond it. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the most popular Twitch streams at the current time, using the verb 'obtiene' and specifying the resource 'streams'. It also distinguishes itself from siblings like get_top_games and get_user_videos by focusing on streams and mentioning optional filtering by game and result limiting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting current popular streams and mentions filter/limit options, but it does not explicitly state when to prefer this tool over alternatives such as search_channels or get_user_videos. No exclusion criteria or alternative tool recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene información detallada de un usuario de Twitch por su nombre de usuario (login). Devuelve ID, nombre para mostrar, descripción, vista previa de perfil, fecha de creación, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| login | Yes | Nombre de usuario de Twitch (login name, en minúsculas) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full transparency burden. It discloses returned fields but omits operational behavior like authentication requirements, rate limits, or error handling for unknown users. 'Obtiene información' suggests a safe read but does not explicitly state non-mutation or other constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and quickly lists relevant returned fields. It is free of filler, and the trailing 'etc.' is an acceptable abbreviation for an open-ended list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple—one required parameter, no output schema—so the description's field list (ID, display name, description, avatar, creation date) meaningfully covers return expectations. However, it does not mention not-found behavior or authentication prerequisites, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the 'login' parameter (Twitch username, lowercase), giving 100% schema coverage. The description only paraphrases that it looks up by login, adding no new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed Twitch user information by login, using the specific verb 'Obtiene' and a defined resource. It distinguishes itself from sibling tools like check_user_live or get_user_videos, which target different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as check_user_live or get_creator_insights. Usage is only implied by the phrase 'por su nombre de usuario', with no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera los clips más populares de un canal en una ventana de tiempo configurable.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Cantidad máxima de clips a devolver (1-100) | |
| login | Yes | Nombre de usuario del canal | |
| window_days | No | Cantidad de días hacia atrás para buscar clips |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only operation ('Recupera') and a time-window filter, but no annotations are present to confirm safety or output traits. It does not explain what 'más populares' means, the return format, or edge cases such as no clips found, leaving the agent to infer these details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one focused sentence with no filler, front-loading the verb and resource. It is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the core purpose but lacks necessary context for a tool with no output schema and no annotations: response format, sorting rule behind 'más populares', and behavior when no clips exist or the window is empty. It is sufficient for invoking the tool but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are documented in the schema (100% coverage), so the description does not need to add parameter semantics. The phrase 'ventana de tiempo configurable' mirrors the window_days parameter description but adds no new information about limit or login.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a channel's most popular clips within a configurable time window, using the specific verb 'Recupera' and a concrete resource ('clips más populares de un canal'). This distinguishes it from siblings like get_user_videos, which concern videos rather than clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_user_videos or check_user_live. The description only restates the function without exclusions, prerequisites, or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene los videos de un usuario de Twitch. Puede filtrar por tipo (archive/VODs, highlight, upload) y limitar la cantidad de resultados.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número máximo de videos a devolver (1-100) | |
| login | Yes | Nombre de usuario de Twitch | |
| video_type | No | Tipo de video: 'archive' (VODs), 'highlight' (clips destacados), 'upload' (subidos), 'all' (todos) | archive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It discloses that it can filter by video type and limit results, which is useful. However, it omits behavior like pagination, error handling, or whether authentication is required, leaving some gaps typical for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence in Spanish, front-loaded with the primary action and immediately followed by the key options. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema, no annotations), the description adequately explains how to fetch and filter videos. However, it does not specify the return format or pagination behavior, which would be helpful given no output schema is present, leaving moderate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (login, limit, video_type), so the schema already explains meanings and defaults. The description only echoes the filter and limit capabilities, adding no new semantic detail beyond the schema, making baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Obtiene los videos de un usuario de Twitch') with a direct verb and resource, and distinguishes it from sibling tools like get_user_clips (clips) and get_twitch_user (user info) by focusing on videos. It also highlights filter and limit options, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this to retrieve a Twitch user's videos, optionally filtered by type and limit. However, it does not explicitly state when not to use it or mention alternatives, relying on the tool name and sibling list for differentiation. No exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Busca canales de Twitch por nombre o palabras clave. Útil para descubrir nuevos streamers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número máximo de resultados (1-100) | |
| query | Yes | Término de búsqueda para encontrar canales | |
| live_only | No | Si es true, solo devuelve canales que están en vivo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the search purpose, not details like how live_only filters results, whether limit caps output, or what happens when no matches are found. This lack of behavioral context could lead to incorrect invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two succinct sentences, front-loaded with the primary action and then the use case. Every word is useful, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema, and the description is minimal. It clarifies the core search purpose but omits how filters like live_only affect behavior and what the response looks like. The gaps are notable for an agent selecting parameters, though the tool is relatively simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% description coverage for all parameters, so the baseline is 3. The description adds no additional meaning beyond the query term, saying nothing about limit or live_only semantics. It does not compensate beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Busca canales de Twitch por nombre o palabras clave' (searches Twitch channels by name or keywords). It also provides a use case ('descubrir nuevos streamers') that differentiates it from exact-lookup siblings like get_twitch_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Útil para descubrir nuevos streamers' implies the tool is for exploratory search rather than exact user lookup. It offers clear context but does not explicitly name alternatives or exclusion criteria, such as 'for exact user info, use get_twitch_user instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0check_user_liveget_channel_followersget_creator_insightsget_game_infoget_top_gamesget_top_streamsget_twitch_userget_user_clipsget_user_videossearch_channelsScored across 10 tools
Each tool targets a distinct data retrieval purpose: user profile, live status, videos, top streams, top games, channel search, game details, followers, clips, and aggregated insights. No overlap between them.
Most tools use the 'get_' prefix pattern, but 'check_user_live' and 'search_channels' deviate from that convention. The underlying verb_noun structure is clear and predictable overall.
10 tools is well-scoped for a Twitch read-only API server, covering discovery, user content, and analytics without unnecessary bloat.
The set covers core Twitch data needs: user profiles, live status, videos, clips, followers, top streams/games, search, and insights. Minor gaps exist (e.g., stream schedules) but no critical dead ends for read-only use.
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
Twitch MCP — wraps the Twitch Helix API (read-only)
Manage your Twitch raid-train schedule from an AI assistant: claim, release & trade slots via OAuth.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
