Turn a folder of CSV, Parquet, and JSON files into a single SQL-queryable source for your AI agent.
list_sources — Discover all available tables (one per data file) along with their column counts; the recommended starting point for any workflow.
describe — Inspect a table's column names and data types to understand its structure before querying.
preview — View the first N rows of any table, capped by TABLEBRIDGE_MAX_ROWS.
query — Run read-only SQL (DuckDB dialect) across all loaded tables, supporting SELECT, WITH, DESCRIBE, SUMMARIZE, and JOIN operations across multiple files. Writes and raw file-access functions are blocked for safety. Results are capped; a truncated flag indicates more rows exist.
refresh — Re-scan the data directory to pick up newly added or changed files without restarting the server.
server_info — View effective server configuration: data directory, maximum row cap, and supported file formats (.csv, .tsv, .parquet, .json, .ndjson).
Click on "Install 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.
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.
🔗 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: TabulaRAG
uvx tablebridge # run directly
# or
pip install tablebridge # then run: tablebridgeTABLEBRIDGE_DATA_DIR=/path/to/your/data claude mcp add tablebridge -- uvx tablebridge{
"mcpServers": {
"tablebridge": {
"command": "uvx",
"args": ["tablebridge"],
"env": { "TABLEBRIDGE_DATA_DIR": "/path/to/your/data" }
}
}
}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 tablebridgeTool | 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) |
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;
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.
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.
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.
MIT © Michael Tierney
Show a table's columns and types.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic action and result, but does not disclose behavioral traits like read-only nature, error handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but could include more useful information without becoming verbose. It earns its keep but is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description is adequate but does not fully compensate for the lack of schema descriptions. It explains the basic functionality but not the return value structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description should add meaning to the parameter 'table', but it only implies its purpose without providing format, examples, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show a table's columns and types' clearly states the tool's purpose with specific verb and resource, and it distinguishes from siblings like query (which retrieves data) and list_sources (which lists tables).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives. It does not mention exclusions or prerequisites, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool lists tables with column counts from files in the data directory, implying a read-only operation. No contradictions or missing critical behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, no fluff. Every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema, the description is complete. It explains what the tool does, what data it lists, and positions it as the starting point among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, schema coverage is 100%. The description adds no parameter details but is not needed; baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the tables available to query (one per data file) with column counts.' It distinguishes from siblings by being the starting point to discover available data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Start here,' providing clear context that this tool should be used first. It does not exclude any scenarios but effectively guides the agent to begin with this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the first n rows of a table (capped by TABLEBRIDGE_MAX_ROWS).
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the cap by TABLEBRIDGE_MAX_ROWS, which is a useful behavioral trait. However, it does not disclose other aspects such as what 'first' means (ordering), whether the operation is read-only (likely, but not stated), or any authentication needs. With no annotations, more transparency would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the core functionality. No unnecessary words or information, making it efficient for agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and an output schema, the description covers the basic functionality. It lacks detail on ordering and table identification, but these may be acceptable given the tool's simplicity and the presence of sibling tools for more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'n' parameter by mentioning the cap, which is not in the schema. However, it does not explain the 'table' parameter format or constraints. Given 0% schema description coverage, the description partially compensates but could be more thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the first n rows of a table, with a cap. The verb 'return' and resource 'rows of a table' are specific. It effectively distinguishes itself from siblings like describe (schema) or query (complex queries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like query or describe. The context is implied by naming, but explicit when-to-use/when-not-to-use instructions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses read-only nature, allowed statement types, row cap with truncated flag, and that queries run across loaded tables. This is thorough and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states purpose, second adds constraints and behaviors. It is front-loaded, concise, and every sentence adds value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description doesn't need to detail return values. It covers parameter usage, allowed/rejected operations, and result cap. For a SQL query tool with one parameter, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates fully. It explains that the 'sql' parameter must be a DuckDB dialect query, specifies supported constructs, and warns against writes. This adds significant meaning beyond the string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool runs read-only SQL queries (DuckDB dialect) on loaded tables. The verb 'run' and resource 'read-only SQL query' are specific, and the distinction from siblings is implied by being the general query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states supported (SELECT, WITH, DESCRIBE, SUMMARIZE, JOINs) and rejected (writes, raw file-access) operations. It lacks explicit comparison to siblings like 'describe' or 'preview', but provides clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-scan the data directory (pick up added/changed files) and report the count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly indicates a non-destructive rescan that returns a count, suggesting safe repeated calls. However, it does not explicitly state the lack of side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core action and output without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema (presumably returning a count), the description fully explains the purpose and result. No additional information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema (0 params, 100% coverage), so baseline is 4. The description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Re-scan the data directory (pick up added/changed files) and report the count.' It specifies the action (re-scan), resource (data directory), and outcome (report count), clearly distinguishing it from sibling tools like 'describe' or 'list_sources'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the user wants to detect added/changed files and get a count, but it does not explicitly state when to use this tool versus alternatives (e.g., 'preview' or 'query') or provide conditions when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the effective configuration (data dir, row cap, supported formats).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behaviors beyond reporting configuration (e.g., is it read-only, any side effects). However, the action is clearly non-destructive. No annotations are provided, so the description carries the burden, but it is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. Every word is necessary and earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple info tool with no parameters and an output schema assumed, the description fully covers what the tool does. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description adds no parameter details, but this is acceptable since no parameters exist. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Report' and names the resource 'effective configuration', listing concrete items: data dir, row cap, supported formats. This clearly distinguishes it from sibling tools like describe or query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned, but the tool's name and description imply it's for checking server configuration. Sibling tools are data-focused, so the usage context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0describelist_sourcespreviewqueryrefreshserver_infoEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Michael-WhiteCapData/tablebridge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
