Skip to main content
Glama
Lotería MCP

Lotería MCP

by parrotsoft

🎟️ MCP Lottery

MCP Server for querying lotteries and results via the Lottery Results API.

It exposes two tools that any compatible MCP client (Claude Desktop, Cursor, etc.) can invoke directly from the chat.


📋 Requirements

Tool

Minimum Version

Python

3.10+

uv

latest


Related MCP server: Marvel MCP

⚙️ Installation

1. Clone the repository

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

2. Create virtual environment and install dependencies with uv

uv sync

This will automatically create the .venv environment and install all dependencies declared in pyproject.toml.


🚀 Usage with Claude Desktop

Add the following configuration to the Claude Desktop file:

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"
      ]
    }
  }
}

Note: Replace /absolute/path/to/project/loteria with the actual path of the project on your machine.

Restart Claude Desktop and the server will be available.


🛠️ Available Tools

get_lotteries

Returns the complete list of lotteries available in the API.

No parameters.

Example response:

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

get_resultados

Returns lottery results for a specific date.

Parameter

Type

Description

date

str

Date in YYYY-MM-DD format. Empty = most recent

Example response:

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

🧪 Run in development mode

To test the server directly from the terminal:

uv run mcp dev loteria.py

This opens the MCP Inspector in the browser, where you can call the tools interactively.


📦 Dependencies

Package

Description

httpx

Async HTTP client for API calls

mcp[cli]

Model Context Protocol framework


📁 Project structure

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

📄 License

MIT

Available Tools

2 tools
get_lotteriesA

Obtiene el listado de todas las loterías disponibles.

Consulta el endpoint `/lotteries` de la API de resultados de loterías
y retorna la información de cada lotería registrada (nombre, país, etc.).

Returns:
    dict[str, Any] | None: Diccionario con la lista de loterías disponibles,
    o None si ocurre un error de red o la API no responde.

Example:
    >>> await get_lotteries()
    {"data": [{"id": 1, "name": "Lotería Nacional", ...}, ...]}

Inputs: no named parameters. Returns: result

get_resultadosA

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

Consulta el endpoint `/results/{date}` de la API cuando se proporciona
una fecha, o `/results` para obtener los resultados más recientes.

Args:
    date (str): Fecha en formato `YYYY-MM-DD` para filtrar los resultados.
        Si se pasa una cadena vacía, retorna los resultados más recientes.

Returns:
    dict[str, Any] | None: Diccionario con los resultados de loterías
    para la fecha indicada, o None si ocurre un error de red o la API
    no responde.

Example:
    >>> await get_resultados("2026-04-24")
    {"data": [{"lottery": "Lotería Nacional", "result": "1234", ...}]}

Inputs: date (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one lists all available lotteries, the other retrieves results for a specific date. There is no risk of confusion.

    Naming Consistency5/5

    Both tools follow a consistent 'get_<resource>' pattern in snake_case, using the same language (Spanish) throughout.

    Tool Count3/5

    Two tools is minimal but reasonable for a simple read-only lottery information server. It borders on feeling thin but does not warrant a lower score.

    Completeness3/5

    The server covers listing lotteries and fetching results by date, but lacks features like filtering by lottery or retrieving historical results beyond a single date.

    Related MCP Connectors

    Related MCP Servers