Integration guides

Lottery data inside your AI assistant.

Connect Claude, Cursor, VS Code or your own agent to the Lottevo MCP server and let it read results, history, statistics and the ticket checker directly.

The Lottevo API is also a Model Context Protocol server. An MCP client connected to it can look up a game, read its latest results and its history, rank its numbers and check a ticket — without you writing an integration. It answers with the same data as /v1, under the same key, plan and quotas.

Connect

Setting	Value
URL	`https://api.lottevo.com/mcp`
Transport	Streamable HTTP
Authentication	your API key, as `Authorization: Bearer lv_…` (or `X-Api-Key`)

Claude Code

Code example

claude mcp add --transport http lottevo https://api.lottevo.com/mcp \
  --header "Authorization: Bearer lv_a1b2c3d4e5f6_…"

Cursor, VS Code and other clients with a JSON configuration — the key names differ slightly from one client to the next (mcpServers or servers, url, headers):

Code example

{
  "mcpServers": {
    "lottevo": {
      "url": "https://api.lottevo.com/mcp",
      "headers": { "Authorization": "Bearer lv_a1b2c3d4e5f6_…" }
    }
  }
}

Claude Desktop connects to remote servers through OAuth, which this server does not use yet, so it reaches it through mcp-remote:

Code example

{
  "mcpServers": {
    "lottevo": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.lottevo.com/mcp", "--header", "Authorization: Bearer ${LOTTEVO_API_KEY}"],
      "env": { "LOTTEVO_API_KEY": "lv_a1b2c3d4e5f6_…" }
    }
  }
}

The server authenticates with an API key, not OAuth, so a client that can only connect through an OAuth sign-in cannot use it yet.

Give the assistant its own key: it only reads, so the read scopes are enough, and you can revoke it without touching your integration.

Tools

Tool	What it answers	Needs
`search_lotteries`	Find a game by name or code, by country, US state or continent	`catalog:read`
`get_lottery`	One game: rules, odds, ticket price, schedule, next jackpot, payouts, latest results	`catalog:read`
`get_latest_results`	The latest result of every game, optionally in one country	`draws:read`
`get_draw_history`	One game's past results, between two dates	`draws:read`
`get_draw`	One result with its full prize breakdown	`draws:read`
`get_lottery_statistics`	Most drawn, least drawn and longest absent numbers, pairs and triplets	`statistics:read`
`get_lottery_distributions`	How the draws are spread — sums, odd/even, low/high, neighbours, positions, gaps — beside a fair draw, with a randomness test	`statistics:read`
`check_ticket`	Which past draws a ticket matched and what it would have won	`draws:read` and a plan with the ticket checker
`generate_tickets`	Valid, distinct tickets under filters — odd/even, ranges, sums, never drawn, hot or cold numbers — with how many the filters allow	`statistics:read`
`build_wheel`	A reduced system on the chosen numbers: tickets guaranteeing a number of matches whenever enough of the drawn numbers are among them	`statistics:read`

A client only sees the tools its key can call: a key without statistics:read, or on a plan without the ticket checker, is not offered those tools.

Quotas and limits

Each tool call is one request to the endpoint it reads — get_lottery is GET /v1/lotteries/{code} — and counts against your daily quota like any other. It shows up in the request log of your dashboard under that endpoint, with the user agent lottevo-mcp. Connecting and listing the tools cost nothing, but are held to your key's per-minute rate.

Everything the key is bound by holds here too: the games it covers, how far back your plan's history reaches, its expiry and its revocation.

Errors

A refused tool call comes back as a tool error whose text is the API's own JSON — the same code as on Errors, such as lottery_not_entitled, history_not_included or quota_exceeded with its retry_after. A missing, unknown or revoked key is refused when the client connects, with 401.