LoteríA

MCP Server para consultar loterías y resultados mediante la API de Resultados de Loterías.

Expone dos herramientas que cualquier cliente MCP compatible (Claude Desktop, Cursor, etc.) puede invocar directamente desde el chat.

---

📋 Requisitos

Herramienta	Versión mínima
Python	3.10+
uv	latest

---

⚙️ Instalación

1. Clonar el repositorio

git clone https://github.com/parrotsoft/loteria-mcp
cd loteria

2. Crear entorno virtual e instalar dependencias con uv

uv sync

Esto creará automáticamente el entorno .venv e instalará todas las dependencias declaradas en pyproject.toml.

---

🚀 Uso con Claude Desktop

Agrega la siguiente configuración al archivo de Claude Desktop:

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

{
  "mcpServers": {
    "loteria": {
      "command": "uv",
      "args": [
        "--directory",
        "/ruta/absoluta/al/proyecto/loteria",
        "run",
        "loteria.py"
      ]
    }
  }
}

Nota: Reemplaza /ruta/absoluta/al/proyecto/loteria con la ruta real del proyecto en tu máquina.

Reinicia Claude Desktop y el servidor quedará disponible.

---

🛠️ Herramientas disponibles

get_lotteries

Retorna el listado completo de loterías disponibles en la API.

Sin parámetros.

Ejemplo de respuesta:

{
  "data": [
    { "id": 1, "name": "Lotería Nacional", "country": "MX" },
    { "id": 2, "name": "Melate", "country": "MX" }
  ]
}

---

get_resultados

Retorna los resultados de loterías para una fecha específica.

Parámetro	Tipo	Descripción
date	str	Fecha en formato YYYY-MM-DD. Vacío = más recientes

Ejemplo de respuesta:

{
  "data": [
    { "lottery": "Lotería Nacional", "result": "1234", "date": "2026-04-24" }
  ]
}

---

🧪 Ejecutar en modo desarrollo

Para probar el servidor directamente desde la terminal:

uv run mcp dev loteria.py

Esto abre el MCP Inspector en el navegador, donde puedes llamar las herramientas de forma interactiva.

---

📦 Dependencias

Paquete	Descripción
httpx	Cliente HTTP async para llamadas a la API
mcp[cli]	Framework Model Context Protocol

---

📁 Estructura del proyecto

loteria/
├── loteria.py        # Servidor MCP con las herramientas expuestas
├── main.py           # Punto de entrada alternativo
├── pyproject.toml    # Configuración del proyecto y dependencias
├── uv.lock           # Lock file de dependencias (uv)
├── .gitignore
└── README.md

---

📄 Licencia

MIT