Database Query API - Read-only SQL over Postgres & DuckDB (MCP)

This MCP server is also listed in the machine-readable MCP directory at /.well-known/mcp/servers.json. Connect a transport below and run read-only SQL as a tool call.

A security-hardened, read-only SQL query API exposing two databases as MCP tools for AI clients - an open endpoint for public use and an Auth0-secured endpoint for gated access. Connect from Claude Code, Claude Desktop, Claude.ai (web connectors), Claude in Excel, or any MCP client. Setup instructions in the README.

Both query endpoints take POST with a JSON body, which is the one to use - no URL-length limit and nothing to percent-encode. Each also has a GET variant, listed below, for clients that cannot send a body.

Open MCP endpoint (no auth)

• https://db-mcp.tigzig.com/mcp - Streamable HTTP, the recommended transport (MCP spec 2025-03-26). No API key, no login on any open endpoint - open by design, defended by the multi-layer stack below.

Secured MCP endpoint (Auth0 OAuth)

• https://db-mcp.tigzig.com/mcp-secure - Streamable HTTP, Auth0-gated (recommended). Requires Auth0 login with an email whitelist - same databases and tools as the open endpoint, with authentication on top.

Both engines carry the same tables, joined on match_id, so the endpoint you pick is a choice of SQL dialect, not of format - the same question returns the same answer on either:

• ball_by_ball - every delivery in one table: men's and women's Test, ODI and T20 internationals, plus the IPL. Filter on the gender and team_type columns.
• The same deliveries split by format and gender - ball_by_ball_test_men, ball_by_ball_odi_women, ball_by_ball_ipl and so on, seven in all. Each is a slice of ball_by_ball with identical columns, and they sum to it exactly.
• match_info - one row per match across every format. Who won, by how much, the competition, player of the match, the officials and the match conditions - none of which is in the ball tables. Per-format views such as match_info_odi_men exist too.
• match_players - who played in each match, one row per player per match. people - the player register, one row per person.
• Refreshed twice daily.
• Both read-only at database and application level.
• JSON and TSV output (TSV uses ~70% fewer tokens).

Row counts, column lists and every enforced limit are deliberately not repeated here. They move - twice daily for the counts, and whenever a field is added. The service root at db-mcp.tigzig.com derives the counts per request, and the full reference carries the columns, the guardrails and the refusal messages, generated from the running service. Any query against a wrong table or column also returns a 400 that hands back the real tables, all columns and working calls - so the service will correct you faster than this page could. A wrong number here would be worse than no number.

Pick Postgres or DuckDB on dialect. QUALIFY works on DuckDB and fails on Postgres; date and string functions differ. Standard SELECT, JOIN, GROUP BY, CTEs, window functions and FILTER work on both. If a query works on one endpoint and fails on the other, check the dialect before you check your table names.

Before you count anything. match_info holds every match across every format, so a count there will not reconcile with a count in any single ball table unless you filter on match_type. Those values are uppercase - 'Test' matches nothing - and the current list is in the spec. Test cricket landed in August 2026; before that match_info carried Test matches with no deliveries behind them, so a query you wrote earlier will now return more rows than it used to.

The table names changed in September 2026, and the old ones are gone. odi_ball_by_ball, t20_ball_by_ball_women, match_info_women and the rest of the August names no longer resolve on either engine - they return a 400 saying the relation does not exist. The pattern is now ball_by_ball_<format>_<gender>, so odi_ball_by_ball became ball_by_ball_odi_men. The columns are the same, so a rename is the whole fix. ball_by_ball itself is a live table again, and it is now the whole dataset rather than one format.

The ball-by-ball data comes from Cricsheet, published under the Open Data Commons Attribution License 1.0 (ODC-BY).

TigZig is not affiliated with or endorsed by Cricsheet. Cricsheet is credited as the source of the underlying match data under the terms of the ODC-BY 1.0 licence.

The tables here are derived from it, not a copy: reshaped into two engines, joined to match and player tables and refreshed twice daily. Cricsheet is the source of the underlying match data; any error in the reshaping is ours.

If you build on this API, the same attribution carries to you. ODC-BY asks that you credit the source and make the licence clear to whoever sees your work.

Coverage note. Cricsheet withholds matches featuring the Afghanistan men's team or played in the Afghanistan Premier League (see cricsheet.org/withheld-matches). That exclusion is inherited here, so this is not a complete record of men's internationals.

This covers everything the service returns - SQL results over the REST API, the MCP tools, and the bulk files you download. Provided as is, with no guarantee of accuracy, completeness or availability and no support commitment. Full terms: db-mcp.tigzig.com/terms

The open endpoint is intentionally public - anyone with the URL can query. It is open by design, defended by a multi-layer stack rather than by obscurity:

• Cloudflare WAF + application-level rate limiting.
• Per-IP and global concurrency caps.
• Multi-layer SQL validation. Read-only statements only, with joins, functions and query shape all bounded. The exact allowlist, every enforced limit and the refusal message each one returns are enumerated in the full reference - generated from the running service, so it cannot go stale. It is not repeated here, because a security rule copied into a second place is a security rule that can quietly disagree with itself.
• Schema discovery is readable on purpose, so you can explore the shape without guessing. Server and role catalogs stay blocked.
• Query timeouts with DuckDB engine interrupt.
• Database-level read-only enforcement (Postgres + DuckDB) and container resource limits.
• Error-message sanitization - no internal details leaked.
• Auth0 OAuth with JWT verification on the secured endpoint.

For the broader web-app security checklist (132 items across all stacks), see tigzig.com/security.

This page is the reference - what the endpoints are and how to call them. The guides below are the long-form versions, with worked examples and the edges you only meet in real use:

• A database server you can point an AI agent at - Start here. what this service is, with ball-by-ball cricket behind it: the REST API, the MCP server, and what an agent does with each.
• Demystifying the API errors - what each error actually means and what to do about it, instead of guessing from a status code. Covers every TigZig API, not just this one.
• Your agents and scripts have been talking to me - what real callers actually do, read out of the server logs: the common mistakes, what works, and the patterns worth copying.
• Is it you, or is it me? - the public status page for every TigZig API, so you can check whether a failure is at your end or ours before you start debugging.
• Run your own SQL on the cricket database - worked queries against T20 and ODI ball-by-ball data, free and with no key, plus what the row caps mean in practice.
• Taking the whole dataset as files - the download paths, how the file names are formed, and when a bulk pull is the better move over a query.

Each is a plain page with a Markdown twin, so you can hand a URL straight to an agent. Come back to this page when you want parameter-level detail.

Published so a well-behaved client can plan around them. These are per-IP limits:

• Per IP: 60 requests / minute.
• At most 4 concurrent queries per IP.

You get a 429 with Retry-After and a body naming the budget you crossed.

Avoiding 429s: These are ~1M-row tables, so aggregate or LIMIT server-side in the SQL rather than paginating. One GROUP BY costs a single request where pagination costs dozens.

Every successful response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix epoch seconds), read straight from the running limiter, and Retry-After is set on 429. The current numbers are also published as machine-readable JSON at https://db-mcp.tigzig.com/, derived from live config. Read those at runtime rather than hard-coding the figures above - limits change, and these channels change with them.

No key, no signup.

https://db-mcp.tigzig.com/v1/query/postgres?sql=SELECT%20COUNT(*)%20AS%20balls%20FROM%20ball_by_ball_t20_men

curl -X POST "https://db-mcp.tigzig.com/v1/query/postgres" -H 'Content-Type: application/json' -d '{"sql":"SELECT striker, SUM(runs_off_bat) AS runs, COUNT(*) AS balls FROM ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10","format":"json"}'

There is an open-source edition of this MCP server - an earlier release you can run as your own service or borrow components from. Treat it as a reference implementation rather than a mirror of what is running here: the hosted service has moved on since. Licensed Apache 2.0.

github.com/amararun/shared-fastapi-database-mcp

Built on FastAPI, fastapi-mcp, asyncpg, DuckDB, SlowAPI.

Auth0 OAuth is optional - the repo covers enabling the secured endpoint or running open-only.