PuntersEdge MCP Server

Official MCP server for the PuntersEdge odds API — Australian and New Zealand racing odds (AU thoroughbred, greyhound and harness; NZ thoroughbred and harness) and Australian sports odds: live per-bookmaker prices, the change feed, best-price comparison, full-field results, form, premiership tables, the closing-line archive and feed health, for AI agents. Bookmaker coverage is measured live at puntersedge.online/api/coverage rather than fixed here.

Nothing to install: the hosted server

PuntersEdge also runs a hosted MCP server, for agent platforms that cannot start a local process (the Claude API, the OpenAI Responses API, Copilot Studio, n8n, LangChain) and for anyone who would rather not install anything:

https://api.puntersedge.online/mcp

Send your API key as an X-API-Key header (or Authorization: Bearer <key>). Claude Code, in one line:

claude mcp add --transport http puntersedge https://api.puntersedge.online/mcp --header "X-API-Key: your-key-here"

Each tool call is billed exactly like the REST call behind it. The hosted server has its own tool set with typed output; setup for every client is at puntersedge.online/developers/remote-mcp. This package, described below, is the local server that runs next to your MCP client.

Install

pip install puntersedge-mcp

Configure

Get a free API key (3,000 credits/month, no card) at puntersedge.online/api, then add it to your MCP client config (Claude Desktop, Claude Code, Cursor, or any MCP host):

{
  "mcpServers": {
    "puntersedge": {
      "command": "puntersedge-mcp",
      "env": { "PUNTERSEDGE_API_KEY": "your-key-here" }
    }
  }
}

Claude Code, in one line:

claude mcp add puntersedge --env PUNTERSEDGE_API_KEY=your-key-here -- puntersedge-mcp

Tools

Read only. Nothing here mutates — no key rotation, no billing, no webhook creation. An agent should not be able to rotate its own credentials, change what is billed, or register a URL that will then receive data. Those endpoints exist and are documented; they are reached deliberately, from application code, not from a chat turn.

Racing — live

Racing — results and history

Racing — form and premierships

Sports

Account, health, sandbox

Every tool response includes credits_remaining, and credits_warning once you cross the threshold, so an agent can budget without spending a call on check_usage. Costs are enforced server-side; a 402 is a hard stop, never overage billing.

sports_odds is billed per market requested — markets="h2h,spreads,totals" is three credits, not one — so it has no single figure and the tool description says so rather than naming one that is right only for the default.

Notes for agents

• Racing is not a sport key. There is no sport_key of horse-racing. Racing is under the racing_* tools; categories are horse, greyhound and harness. country filters by ISO code (AU, NZ or AU,NZ); omit it to get every meeting. New Zealand is thoroughbred and harness only — there are no NZ greyhounds in the feed.
• Do not poll racing_next_to_go. It re-downloads every race every time and bills 2 credits for it. racing_changes returns only what moved and hands back the cursor for the next call. The cursor sits 30 seconds behind the server clock so nothing in flight is skipped, which makes the feed at-least-once — expect to see a race twice.
• A stale price looks exactly like a live one. A stalled scraper does not error; it keeps serving its last value. Every racing quote carries age_seconds and stale, and connector_health reports last_ok per bookmaker. Check it before telling someone a market has settled.
• Prices are decimal odds in AUD markets. Every sports market carries a quality object; trust it over assumptions.
• Settle only against status: "final". Interim placings can change on protest.
• Join one thoroughbred across meetings on horse_ref, not runner_ref. Every thoroughbred runner and placing in results, every live-board runner, every archive row and every form response carries horse_ref (pe:<name>), and it is the same value on all of them. runner_ref (ra:<code>) is the code Racing Australia published on race day: it joins the rows about one race (results, the closing-line, price-path and markets archives, the live board on race day), and it changes from meeting to meeting because Racing Australia issues a new code for the same horse each day. Greyhound refs (grv:/grsa:) are per-dog registry ids and do persist.
• Do not loop horse_form over a field or a list. The upstream rate-limits hard. For many horses there is a paced bulk backfill queue, reached from application code. When the answer is a 503 saying Racing Australia is refusing fresh reads, horse_runs is our own record of the horse and does not depend on that page.
• On racing_acceptances, several counts are a floor, not an exact figure, wherever a race reports runner_set_status other than checks_passed. The response's completeness block states the bound. Say "at least N" rather than reporting a field size.
• One book quoting both legs is not an arb. A large apparent edge on a two-outcome market that only one bookmaker is pricing is a data artefact.

Also available

• Rules for coding agents — AGENTS.md, a drop-in instructions file so Claude Code, Cursor or Copilot write correct PuntersEdge code. The MCP server lets an agent read live odds; that file makes it write better clients.
• SDKs — npm install puntersedge (TypeScript/JavaScript), pip install puntersedge (Python).
• Schema — https://api.puntersedge.online/openapi.json.

Development

python3 tests/check_contract.py .        # checks every tool against the live OpenAPI document

That test drives each tool through a stub and verifies three things the runtime will not tell you about: that the path exists, that every query parameter is one the endpoint actually declares, and that the credit cost in the docstring matches what the API charges. It is the test that catches a tool quietly sending a filter the server ignores.

Changelog

0.4.4 — README only: points to the hosted server at https://api.puntersedge.online/mcp, which needs no install. No tool changes.

0.4.3 — racing_closing_lines states the archive's plan gate: Plus and above read the whole archive, Standard reads a rolling window (each response's window_days says which applies to your key), and Free and Hobby get a 403. racing_next_to_go describes the British and Irish card (country=GB,IE): the UK-licensed books plus the Australian books that quote it, with place prices derived from each-way terms.

0.4.1 — Listed on the official MCP Registry as io.github.Propertyscout001/puntersedge; the README carries the registry's ownership line. No tool changes.

0.4.0 — New racing_markets tool: every market on one race — win, place, Same Race Multi Top 2/3/4, and the exotic dividends once it has run (2 credits, Plus and above). 31 tools. racing_next_to_go serves every country, and the free tier is 3,000 credits. On a thoroughbred, runner_ref is the code Racing Australia published on race day and joins the rows about one race; Racing Australia issues a new code for the same horse each day, so horse_ref is the key across meetings.

0.3.0 — runner_ref on thoroughbreds is not a horse identity, and this package said it was. It is Racing Australia's code for that day's entry and changes from meeting to meeting; horse_ref (pe:<name>), now on every thoroughbred surface, is the join key. Tool texts, the server instructions and the notes above say so. New horse_runs tool: one horse's runs in our own settled results (3 credits), the fallback when Racing Australia refuses a fresh form read. Also new: racing_clv (score up to 200 bets against the closing line, 5 credits, Plus and above — the server's first POST tool), check_overage and bulk_datasets (both free). greyhound_stats no longer claims a grade dimension.

0.2.1 — The "Rules for coding agents" link named github.com/puntersedge/puntersedge-examples. That account exists and belongs to someone else; ours is Propertyscout001. Documentation only.

0.2.0 — 16 new tools (change feed, events, track conditions, acceptances, venues, results coverage, closing lines and coverage, horse and greyhound form, greyhound stats, jockey and trainer premierships, cross-book comparison, connector health, sports sandbox). Corrected three understated credit costs: best_odds said 2 and is 3, racing_price_history said 3 and is 5, sports_odds said 2 and is one per market. Removed num_races from racing_movers — that endpoint has no such parameter, so the filter had silently done nothing since 0.1.0; use limit. Status-specific error hints, and a contract test to stop all of that recurring.

0.1.1 — Package text says Australian and New Zealand racing, with no fixed book count.

0.1.0 — First release.