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.

Install

pip install puntersedge-mcp

Configure

Get a free API key (1,500 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 Racing Australia's code for that day's entry and changes from meeting to meeting (measured 21 Sep 2026: 1,450 of 1,452 horses with two or more runs carried a different code on each), so it joins a row to its own meeting only. 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.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.