duckdb-spatial-docsbox-mcp read-only

An MCP (Model Context Protocol) server that lets an LLM agent safely explore and query a DuckDB database with the spatial extension. File-mode databases are opened with read_only=True; all SQL is statically validated before execution and bounded by a per-statement wall-clock timeout (enforced via connection.interrupt()).

Endpoints

GET / — this page
GET /health — JSON health
POST /mcp — MCP streamable HTTP transport
GET /llms.txt · /llms-full.txt · /robots.txt · /sitemap.xml

Tools

Tool	Purpose
`list_tables`	User tables/views with row count & geometry flag.
`get_table_schema`	DDL + sample rows + indexes for one table.
`get_column_values`	Distinct sample values for one column.
`list_srids`	SRIDs in active use (DuckDB stores all geometry as SRID 0).
`get_relationships`	Foreign-key edges.
`list_extensions`	Loaded/installed DuckDB extensions (spatial, parquet, ...).
`pick_interesting_tables`	Score by rows + geometry + R-Tree + FK hubness.
`validate_sql`	Static SQL safety check (no DB needed).
`explain_sql`	EXPLAIN [ANALYZE] text plan.
`execute_sql`	Read-only SELECT/WITH/EXPLAIN with row caps.
`list_gdal_drivers`	Installed GDAL drivers exposed via `ST_Drivers()`.
`probe_external_file`	Peek schema/sample of a CSV / Parquet / GeoJSON / SHP / GPKG file.
`duckdb_help`	Curated DuckDB+spatial recipe reference.
`list_sections` / `get_documentation`	Doc manifest browser.
`run_locally`	Plan-only execution recipes (duckdb CLI, EXPORT DATABASE, ST_Read, ...).

Configure

export DUCKDB_DOCSBOX_PATH=/path/to/file.duckdb   # or :memory:
duckdb-spatial-docsbox-mcp

opencode / Claude Code

{
  "mcpServers": {
    "duckdb-spatial-docsbox": {
      "type": "http",
      "url": "http://127.0.0.1:7821/mcp"
    }
  }
}