🎟️ 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

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.

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

📁 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