Skip to main content
Glama
deenesjakoruzh
parrotsoft

Lotería MCP

by parrotsoft
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

🎟️ Лотерея MCP

MCP-сервер для запроса лотерей и результатов через API результатов лотерей.

Предоставляет два инструмента, которые любой совместимый MCP-клиент (Claude Desktop, Cursor и т. д.) может вызвать непосредственно из чата.

📋 Требования

Инструмент

Минимальная версия

Python

3.10+

uv

latest

Related MCP server: Marvel MCP

⚙️ Установка

1. Клонирование репозитория

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

2. Создание виртуального окружения и установка зависимостей с помощью uv

uv sync

Это автоматически создаст окружение .venv и установит все зависимости, указанные в pyproject.toml.

🚀 Использование с Claude Desktop

Добавьте следующую конфигурацию в файл 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"
      ]
    }
  }
}

Примечание: Замените /ruta/absoluta/al/proyecto/loteria на реальный путь к проекту на вашем компьютере.

Перезапустите Claude Desktop, и сервер станет доступен.

🛠️ Доступные инструменты

get_lotteries

Возвращает полный список лотерей, доступных в API.

Без параметров.

Пример ответа:

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

get_resultados

Возвращает результаты лотерей за определенную дату.

Параметр

Тип

Описание

date

str

Дата в формате YYYY-MM-DD. Пусто = самые последние

Пример ответа:

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

🧪 Запуск в режиме разработки

Для тестирования сервера непосредственно из терминала:

uv run mcp dev loteria.py

Это откроет MCP Inspector в браузере, где вы сможете вызывать инструменты в интерактивном режиме.

📦 Зависимости

Пакет

Описание

httpx

Асинхронный HTTP-клиент для вызовов API

mcp[cli]

Фреймворк Model Context Protocol

📁 Структура проекта

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

📄 Лицензия

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", ...}, ...]}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly states the tool returns a dict or None on network error, and that it queries an API. It does not mention auth or rate limits, but for a read-only list tool, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three parts: purpose, endpoint, and return type with example. Each sentence adds value without redundancy, making it well-structured and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity, no parameters, and existence of an output schema, the description fully suffices. It explains the return structure and includes an example, meeting completeness requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, and schema coverage is 100%. Per the guidelines, a baseline of 4 is assigned for zero parameters, and the description adds no further parameter info, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it obtains the list of all available lotteries by querying the /lotteries endpoint, providing specific verb and resource. The sibling tool 'get_resultados' is for results, so this tool is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. Usage is implied by the tool's purpose but not articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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", ...}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the burden. It explains that it queries an API endpoint, returns a dict or None on network error, and includes an example. This is adequate disclosure of behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is structured in sections (Args, Returns, Example) and front-loaded. It is slightly verbose but still efficient for the information provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 param, output schema present), the description covers purpose, parameter semantics, return type, and error cases. It does not mention the sibling tool, but completeness is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description contains an extensive 'Args' section explaining the single parameter 'date'—format, behavior when empty, and example. It adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool obtains lottery results for a specific date ('Obtiene los resultados de loterías para una fecha específica'). It distinguishes from the sibling tool 'get_lotteries' which likely lists lotteries, but does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool instead of the sibling 'get_lotteries'. The description provides parameter usage (empty string for most recent) but not tool selection context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedget_lotteries
    • First observedget_resultados
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers