tablebridge
It is an MCP server that turns a folder of CSV/Parquet/JSON files into read-only SQL-queryable tables for AI agents.
list_sources — see every available table (one per data file) and its column count.
describe — inspect a table's columns and data types.
preview — return the first N rows of a table (capped by
TABLEBRIDGE_MAX_ROWS).query — run read-only DuckDB SQL, including
SELECT,WITH,DESCRIBE,SUMMARIZE, and JOINs across files; writes and raw file-access functions are blocked.refresh — re-scan the data directory to pick up added or changed files.
server_info — show effective config: data directory, row cap, supported formats.
Supports
.csv,.tsv,.parquet,.json, and.ndjsonfiles, with optional recursive subdirectory scanning.Security features: sandboxed to the data directory, files materialized in-memory, and SQL validated to be read-only.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tablebridge Show me total revenue per region by joining orders and regions tables."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tablebridge
Turn a folder of CSV / Parquet / JSON files into one SQL-queryable source for your AI agent.
Small businesses don't have a data warehouse — they have a folder full of exports: customers.csv, last month's orders.xlsx, a regions.json someone emailed over. tablebridge is an MCP server that points DuckDB at that folder, exposes each file as a SQL table, and lets your agent run read-only SQL — including JOINs across files — to answer questions over all of them at once. Scattered spreadsheets become one queryable source of truth.
It's read-only and sandboxed: files are loaded into an in-memory database, the data directory is the only thing it can see, and queries are validated so an agent can't write, escape to other paths, or call raw file functions.
Why you'd want this
🔗 One source over many files. JOIN
orders.csvtocustomers.csvtoregions.jsonin a single query — no ETL, no database to stand up.🦆 DuckDB-powered. Fast analytical SQL over CSV, TSV, Parquet, JSON/NDJSON.
🔒 Safe by design. Files are materialized into memory; queries are validated read-only; raw file-access functions and out-of-sandbox paths are rejected.
🤖 Agent-friendly.
list_sources→describe→queryis a natural flow the agent can follow on its own.🪶 Two dependencies (
mcp,duckdb), fully typed and tested.
Related MCP server: duckdb-mcp
Install
uvx tablebridge # run directly
# or
pip install tablebridge # then run: tablebridgeTablebridge uses the MCP Python SDK 1.x FastMCP API. Its dependency range stays
below SDK 2 until the server is migrated to that API.
Claude Code
TABLEBRIDGE_DATA_DIR=/path/to/your/data claude mcp add tablebridge -- uvx tablebridgeClaude Desktop / Cursor
{
"mcpServers": {
"tablebridge": {
"command": "uvx",
"args": ["tablebridge"],
"env": { "TABLEBRIDGE_DATA_DIR": "/path/to/your/data" }
}
}
}Run with Docker
A Dockerfile is included. The server speaks MCP over stdio. Mount the
folder you want to query at /data (read-only is fine) and run interactively (-i):
docker build -t tablebridge .
docker run --rm -i -v /path/to/your/data:/data:ro tablebridgeTools
Tool | Description |
| List the tables (one per data file) with column counts — start here |
| A table's columns and types |
| First N rows of a table |
| Run read-only SQL (DuckDB dialect) across the tables, JOINs included |
| Re-scan the data directory for added/changed files |
| Effective config (data dir, row cap, supported formats) |
Example
With a folder containing customers.csv, orders.csv, and regions.json:
You: Who are my top 3 customers by total spend, and what region are they in?
Agent: (calls
list_sources, thenquery)SELECT c.name, r.region, SUM(o.total) AS spend FROM customers c JOIN orders o ON o.customer_id = c.id JOIN regions r ON r.customer_id = c.id GROUP BY c.name, r.region ORDER BY spend DESC LIMIT 3;
Configuration
Variable | Default | Description |
|
| Directory of files to expose (the sandbox boundary) |
|
| Max rows returned per query/preview |
|
| Scan subdirectories too |
Supported formats: .csv, .tsv, .parquet, .json, .ndjson.
Security model
Sandboxed to
TABLEBRIDGE_DATA_DIR— only files under it are loaded.Materialized into an in-memory DuckDB, then external filesystem access is disabled — queries can't reach other paths.
Validated SQL — a single read-only statement only; writes and raw file-reader functions are rejected.
Development
git clone https://github.com/Michael-WhiteCapData/tablebridge-mcp
cd tablebridge-mcp
uv pip install -e ".[dev]"
ruff check .
pytest # uses real DuckDB over temp filesSee CONTRIBUTING.md.
License
MIT © Michael Tierney
Available Tools
6 toolsdescribeC
Show a table's columns and types.
Inputs: table (required). Returns: result
list_sourcesA
List the tables available to query (one per data file) with column counts.
Start here: each CSV/Parquet/JSON file under the data directory is exposed as a table you can SELECT from and JOIN across.
Inputs: no named parameters. Returns: result
previewA
Return the first n rows of a table (capped by TABLEBRIDGE_MAX_ROWS).
Inputs: table (required), n. Returns: result
queryA
Run a read-only SQL query (DuckDB dialect) across the loaded tables.
Supports SELECT / WITH / DESCRIBE / SUMMARIZE and JOINs across files. Writes
and raw file-access functions are rejected. Results are capped at
TABLEBRIDGE_MAX_ROWS; a truncated flag indicates when more rows exist.
Inputs: sql (required). Returns: result
refreshA
Re-scan the data directory (pick up added/changed files) and report the count.
Inputs: no named parameters. Returns: result
server_infoA
Report the effective configuration (data dir, row cap, supported formats).
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: describe for schema, list_sources for table listing, preview for row sampling, query for SQL execution, refresh for data reload, and server_info for configuration. No overlap.
Most tools use single imperative verbs (describe, preview, query, refresh) but list_sources uses verb_noun and server_info uses noun_noun. The pattern is mostly consistent but has minor deviations.
With 6 tools, the server covers all core functionalities needed for data exploration and querying without excess or deficiency. The scope is well-matched.
The tool set provides essential operations: listing, describing, previewing, querying, refreshing, and configuration. A minor gap could be the absence of a statistical summary tool, but the core workflow is fully covered.
Related MCP Connectors
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Every spreadsheet is a table: Excel, CSV, Parquet and JSON as SQL tables for AI agents.
Push CSV, JSON, JSONL or Parquet from your agent and get a link a human can explore.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceQuery local CSV, Parquet, JSON and TSV files with real SQL via DuckDB. Gives your AI coding tool ground-truth data access instead of hallucinated answers.5MIT
- AlicenseAqualityDmaintenanceEnables read-only SQL querying and exploration of data files (CSV, Parquet, JSON, Excel, etc.) via DuckDB, supporting local paths, globs, URLs, and S3 buckets.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to analyze large CSV files locally by importing them into SQLite, profiling columns, and running read-only SQL queries without data leaving the machine.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants and MCP clients to ask natural-language questions about DuckDB or CSV data and receive safe, read-only SQL-generated tabular insights with automatic schema discovery and multi-table joins.1-