Skip to main content
Glama

tablebridge

Turn a folder of CSV / Parquet / JSON files into one SQL-queryable source for your AI agent.

CI PyPI Python MCP License: MIT

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.

Related MCP server: duckdb-mcp

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

Tool

Description

list_sources

List the tables (one per data file) with column counts — start here

describe

A table's columns and types

preview

First N rows of a table

query

Run read-only SQL (DuckDB dialect) across the tables, JOINs included

refresh

Re-scan the data directory for added/changed files

server_info

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

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

TABLEBRIDGE_DATA_DIR

.

Directory of files to expose (the sandbox boundary)

TABLEBRIDGE_MAX_ROWS

1000

Max rows returned per query/preview

TABLEBRIDGE_RECURSIVE

1

Scan subdirectories too

Supported formats: .csv, .tsv, .parquet, .json, .ndjson.

Security model

  1. Sandboxed to TABLEBRIDGE_DATA_DIR — only files under it are loaded.

  2. Materialized into an in-memory DuckDB, then external filesystem access is disabled — queries can't reach other paths.

  3. 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 files

See CONTRIBUTING.md.

License

MIT © Michael Tierney

Available Tools

6 tools
describeC

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

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    With 6 tools, the server covers all core functionalities needed for data exploration and querying without excess or deficiency. The scope is well-matched.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Query 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.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables read-only SQL querying and exploration of data files (CSV, Parquet, JSON, Excel, etc.) via DuckDB, supporting local paths, globs, URLs, and S3 buckets.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -