Tablebridge MCP server

<!-- mcp-name: io.github.Michael-WhiteCapData/tablebridge-mcp -->

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.csv to customers.csv to regions.json in 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 → query is a natural flow the agent can follow on its own.
• 🪶 Two dependencies (mcp, duckdb), fully typed and tested.

Install

uvx tablebridge          # run directly
# or
pip install tablebridge  # then run: tablebridge

Tablebridge 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 tablebridge

Claude 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 tablebridge

Tools

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 listsources, then query)*

sql

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

Shortened. The full README is on GitHub.