# MCP Server: Database (Cricket SQL)

Read-only SQL query API for Postgres and DuckDB, exposed as MCP tools for AI clients. Contains ~1M rows of ODI cricket data (Postgres/Supabase) and ~1M rows of T20 cricket data (DuckDB).

## Links
- App: https://rbicc.net/mcp-server-database
- GitHub: https://github.com/amararun/shared-fastapi-database-mcp
- Live API: https://db-mcp.tigzig.com
- MCP Endpoint: https://db-mcp.tigzig.com/mcp
- API Docs: https://db-mcp.tigzig.com/docs

## Tags
database-ai, mcp-servers, duckdb, postgresql, cricket

## Architecture

```
MCP Client (Claude Code/Desktop) → FastAPI Server → Postgres (Supabase, ODI data)
                                                  → DuckDB (T20 data, read-only)
```

Two databases, two endpoints, one MCP server. Both tables have identical 23-column schemas covering match details, player info, runs, extras, and dismissals.

### Endpoints
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/query/postgres` | SQL query on ODI data (Supabase) |
| POST | `/api/query/duckdb` | SQL query on T20 data (DuckDB) |
| GET | `/health` | Health check with DB connectivity |
| GET | `/mcp` | MCP SSE endpoint for AI clients |

### Query Format
```json
{"sql": "SELECT striker, SUM(runs_off_bat) as runs FROM ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10", "format": "json"}
```
Set `"format": "tsv"` for compact output (~70% fewer tokens).

### Connecting as MCP Client

**Claude Code:**
```bash
claude mcp add --transport sse db-mcp https://db-mcp.tigzig.com/mcp
```

**Claude Desktop** (claude_desktop_config.json):
```json
{"mcpServers": {"db-mcp": {"type": "sse", "url": "https://db-mcp.tigzig.com/mcp"}}}
```

### Security
- SQL blocklist prevents write operations (INSERT, DROP, ALTER, etc.)
- Only SELECT/SHOW/DESCRIBE/EXPLAIN/WITH allowed
- Postgres: `SET default_transaction_read_only = on`
- DuckDB: `read_only=True`, `enable_external_access = false`
- Rate limiting via SlowAPI
- Query timeouts on both databases

### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SUPABASE_POSTGRES` | Yes | Postgres connection string |
| `DUCKDB_FILE` | Yes | Path to .duckdb file |
| `RATE_LIMIT` | No | Default: 60/hour |
| `PG_STATEMENT_TIMEOUT_MS` | No | Default: 30000 |
| `MAX_JSON_ROWS` | No | Default: 10000 |
| `MAX_TSV_ROWS` | No | Default: 50000 |

### Stack
FastAPI, uvicorn, asyncpg (Postgres pool), DuckDB (read-only), fastapi-mcp v0.4.0, SlowAPI

## Setup

```bash
git clone https://github.com/amararun/shared-fastapi-database-mcp.git
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Configure Postgres connection + DuckDB path
uvicorn app:app --host 0.0.0.0 --port 8000
```