Referencia del servidor MCP de Loteria API
Herramientas, parámetros, coste y errores del servidor MCP de loterías españolas, y cómo configurarlo en Claude Code, Codex, Cursor, VS Code, la API de Claude, claude.ai y ChatGPT. Para una presentación más corta, mira MCP de loterías para IA.
Resumen
- URL:
https://api.loteriasapi.com/mcp - Transporte: Streamable HTTP sin estado (JSON-RPC 2.0 por POST), protocolo 2025-06-18.
- Autenticación: opcional.
X-API-Key: lat_...oAuthorization: Bearer lat_.... - Sin key: 5 herramientas, 3 últimos sorteos, 60 llamadas por minuto por IP.
- Con key: 10 herramientas, límites de tu plan, 300 llamadas por minuto por key.
- Todas las herramientas son de solo lectura e idempotentes.
- Metadatos: server card.
Configuración por cliente
Claude Code
claude mcp add --transport http loterias https://api.loteriasapi.com/mcp
# con API key
claude mcp add --transport http loterias https://api.loteriasapi.com/mcp \
--header "X-API-Key: $LOTERIAS_API_KEY"Codex
export LOTERIAS_API_KEY=lat_...
codex mcp add loterias --url https://api.loteriasapi.com/mcp --bearer-token-env-var LOTERIAS_API_KEYO en ~/.codex/config.toml:
[mcp_servers.loterias]
url = "https://api.loteriasapi.com/mcp"
bearer_token_env_var = "LOTERIAS_API_KEY"Cursor y clientes con mcpServers
En ~/.cursor/mcp.json o el fichero de tu cliente:
{
"mcpServers": {
"loterias": {
"url": "https://api.loteriasapi.com/mcp",
"headers": { "X-API-Key": "lat_..." }
}
}
}VS Code
En .vscode/mcp.json; VS Code pide la key la primera vez y la guarda cifrada:
{
"servers": {
"loterias": {
"type": "http",
"url": "https://api.loteriasapi.com/mcp",
"headers": { "X-API-Key": "${input:loterias-key}" }
}
},
"inputs": [
{ "id": "loterias-key", "type": "promptString", "description": "API key de Loteria API", "password": true }
]
}API de Claude
Con la cabecera anthropic-beta: mcp-client-2025-11-20; la key va en authorization_token:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{ "role": "user", "content": "¿Qué salió en la última Primitiva?" }
],
"mcp_servers": [
{
"type": "url",
"url": "https://api.loteriasapi.com/mcp",
"name": "loterias",
"authorization_token": "lat_..."
}
],
"tools": [{ "type": "mcp_toolset", "mcp_server_name": "loterias" }]
}claude.ai y ChatGPT
Añade un conector personalizado con la URL y sin autenticación. Solo funciona el modo gratuito: estos conectores no permiten enviar una API key en una cabecera. Pasos para usuarios en comprobar la lotería con ChatGPT o Claude.
Herramientas
Sin key, tools/list devuelve las 5 herramientas gratuitas. Si un agente llama sin key a una herramienta que la necesita, recibe un resultado con isError: true que explica cómo conectarse con key.
list_games
Lista los juegos con su identificador (slug), que es el valor de game en el resto de herramientas.
get_latest_results
Últimos resultados de un juego, del más reciente al más antiguo: fecha, drawId, combinación, complementarios y bote. Sin key, hasta 3 sorteos.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
limit | integer | No | Cuántos sorteos. Sin key, de 1 a 3; con key, hasta el máximo por petición de tu plan. Por defecto 1. |
includePrizes | boolean | No | Incluye el reparto de premios de cada sorteo. Por defecto false, para respuestas cortas. Solo con key. |
get_next_draw
Próximo sorteo de un juego: fecha, estado y bote anunciado si lo hay.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
check_numbers
Comprueba si unos números o décimos tienen premio en un sorteo (por defecto, el último): aciertos, si es ganador y el premio. Sin key, solo en los 3 últimos sorteos.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
numbers | (integer | string)[] | Sí | De 1 a 20 números. En nacional, hasta 5 décimos de 1 a 5 cifras; pásalos como texto para conservar los ceros ("01755"). |
extraNumbers | integer[] | No | Hasta 5: estrellas de Euromillones, reintegro de Primitiva y Bonoloto, número clave... |
drawId | string | No | Identificador del sorteo que devuelven las herramientas de resultados. Solo con key. |
drawDate | string (YYYY-MM-DD) | No | Fecha del sorteo. Sin key, debe ser uno de los 3 últimos. Se ignora si hay drawId. |
get_public_statistics
Estadísticas agregadas de los últimos 2000 sorteos: números más y menos frecuentes, ausencias más largas, pares e impares, rango de sumas y parejas más repetidas. Para primitiva, bonoloto, euromillones, gordo, eurodreams y lototurf.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
search_results
Busca en el histórico de un juego, del más reciente al más antiguo, con filtros y páginas. Los días de histórico dependen de tu plan.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
from | string (YYYY-MM-DD) | No | Fecha inicial, incluida. |
to | string (YYYY-MM-DD) | No | Fecha final, incluida. |
year | integer | No | Limita a un año natural (1900-2100). |
minJackpot | integer | No | Bote mínimo en euros. |
page | integer | No | Página, desde 1. meta.hasNext indica si hay más. |
limit | integer | No | Sorteos por página, hasta el máximo de tu plan. Por defecto 10. |
includePrizes | boolean | No | Incluye el reparto de premios de cada sorteo. Por defecto false, para respuestas cortas. |
get_result_by_date
Resultado de un juego en una fecha, siempre con el reparto de premios. Lista vacía si ese día no hubo sorteo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
date | string (YYYY-MM-DD) | Sí | Fecha del sorteo. |
get_statistics
Estadísticas generales: total de sorteos, rango de fechas, números calientes y fríos, bote mayor y medio y días medios entre botes.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
year | integer | No | Limita a un año natural (1900-2100). |
get_number_frequencies
Frecuencia de cada número: veces que ha salido, porcentaje y última fecha.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
year | integer | No | Limita a un año natural (1900-2100). |
limit | integer | No | Cuántos números. Por defecto 50. |
get_jackpot_history
Historial de botes: fecha, importe, si se ganó y número de acertantes.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
year | integer | No | Limita a un año natural (1900-2100). |
limit | integer | No | Cuántas entradas. Por defecto 50. |
get_patterns
Patrones: pares e impares, altos y bajos, consecutivos, distribución de sumas, parejas y tríos más comunes.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
game | string | Sí | Juego: bonoloto, euromillones, lototurf, primitiva, gordo, quiniela, quinigol, quintuple (o quinto), nacional, eurodreams. |
year | integer | No | Limita a un año natural (1900-2100). |
Respuestas
Cada resultado trae los datos dos veces: como texto JSON en content y como objeto en structuredContent. Las listas de sorteos omiten los premios salvo con includePrizes. Con key, la respuesta incluye un objeto plan con los límites de tu plan y las peticiones aproximadas que te quedan:
"plan": {
"name": "Pro",
"maxItemsPerRequest": 50,
"historyDays": 365,
"requestsRemaining": 18420
}Ejemplo de llamada directa:
curl -s https://api.loteriasapi.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "X-API-Key: $LOTERIAS_API_KEY" \
-d '{
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {
"name": "check_numbers",
"arguments": { "game": "nacional", "numbers": ["01755"] }
}
}'Coste y límites
- Con key, cada llamada gasta 1 petición del plan, igual que la API REST.
list_games,get_next_drawy las llamadas que fallan no gastan.check_numberscondrawDatey sindrawIdgasta 2: una para encontrar el sorteo.- Sin key no se gasta nada; el límite es de 60 llamadas por minuto por IP.
- Máximo de sorteos por petición y días de histórico: los de tu plan (límites, planes).
Errores
- Errores de una herramienta (argumentos no válidos, key rechazada, cuota agotada): resultado normal con
isError: truey un mensaje para el agente. - Key rechazada: el mensaje enlaza al panel de API keys para revisarla.
- Cuota agotada (402): el mensaje enlaza a los planes.
- Límite por minuto: HTTP 429 con error JSON-RPC
-32000; con key, el mensaje indica cuántos segundos esperar. - Protocolo:
-32700JSON mal formado,-32600petición no válida,-32601método desconocido,-32602herramienta o argumentos no válidos.