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

6 endpoints. Request bodies, every field and every enforced limit are in the full reference.

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:

• One ball-by-ball table per format - test_ball_by_ball, odi_ball_by_ball, t20_ball_by_ball. One row per delivery, men's internationals. All three share an identical column contract, so a query runs against any of them by changing the table name.
• match_info - one row per match. 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.
• 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 old table names are gone. odi_cricket_ball_by_ball and ball_by_ball were the original names and survived for a while as views. Neither resolves on either engine any more - both now return a 400 saying the relation does not exist. If you have a query written before August 2026, rename the table to odi_ball_by_ball or t20_ball_by_ball; nothing else about it needs to change, the columns are the same.

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, filtered to men's internationals, joined to a match-level table 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 (120 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:

• 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.

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%20odi_ball_by_ball

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 odi_ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10","format":"json"}'

{"format":"json","columns":["striker","runs","balls"],
 "rows":[
        ["Asif Khan",610,678],
        ["SC Williams",600,437],
        ["V Aravind",549,787],
        ["P Nissanka",508,613],
        ["Waseem Muhammad",501,522],
        ["DJ Mitchell",493,503],
        ["SD Hope",489,529],
        ["Babar Azam",483,515],
        ["HT Tector",478,512],
        ["BA King",468,528]
 ],
 "row_count":10, "truncated":false}

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.