tablebridge

tablebridge

Convierte una carpeta de archivos CSV / Parquet / JSON en una única fuente consultable con SQL para tu agente de IA.

Las pequeñas empresas no tienen un almacén de datos — tienen una carpeta llena de exportaciones: customers.csv, el orders.xlsx del mes pasado, un regions.json que alguien envió por correo. tablebridge es un servidor MCP que apunta DuckDB a esa carpeta, expone cada archivo como una tabla SQL y permite que tu agente ejecute SQL de solo lectura — incluyendo JOINs entre archivos — para responder preguntas sobre todos ellos a la vez. Las hojas de cálculo dispersas se convierten en una única fuente de verdad consultable.

Es de solo lectura y está aislado: los archivos se cargan en una base de datos en memoria, el directorio de datos es lo único que puede ver, y las consultas se validan para que un agente no pueda escribir, escapar a otras rutas ni llamar a funciones de archivo sin procesar.

---

Por qué querrías esto

• 🔗 Una sola fuente sobre muchos archivos. Combina orders.csv con customers.csv y regions.json en una sola consulta — sin ETL, sin necesidad de montar una base de datos.
• 🦆 Impulsado por DuckDB. SQL analítico rápido sobre CSV, TSV, Parquet, JSON/NDJSON.
• 🔒 Seguro por diseño. Los archivos se materializan en memoria; las consultas se validan como solo lectura; se rechazan las funciones de acceso a archivos sin procesar y las rutas fuera del entorno aislado.
• 🤖 Amigable para agentes. list_sources → describe → query es un flujo natural que el agente puede seguir por sí solo.
• 🪶 Dos dependencias (mcp, duckdb), completamente tipado y probado.

Instalación

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

Tablebridge utiliza la API FastMCP del SDK de MCP Python 1.x. Su rango de dependencias se mantiene por debajo del SDK 2 hasta que el servidor se migre a esa 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" }
    }
  }
}

Ejecutar con Docker

Se incluye un Dockerfile. El servidor habla MCP a través de stdio. Monta la carpeta que quieras consultar en /data (solo lectura está bien) y ejecuta de forma interactiva (-i):

docker build -t tablebridge .
docker run --rm -i -v /path/to/your/data:/data:ro tablebridge

Herramientas

Herramienta	Descripción
list_sources	Lista las tablas (una por archivo de datos) con recuentos de columnas — empieza aquí
describe	Las columnas y tipos de una tabla
preview	Primeras N filas de una tabla
query	Ejecuta SQL de solo lectura (dialecto DuckDB) en todas las tablas, incluidos JOINs
refresh	Vuelve a escanear el directorio de datos en busca de archivos añadidos/modificados
server_info	Configuración efectiva (directorio de datos, límite de filas, formatos admitidos)

Ejemplo

Con una carpeta que contiene customers.csv, orders.csv y regions.json:

Tú: ¿Quiénes son mis 3 mejores clientes por gasto total y en qué región están?

Agente: (llama a list_sources, luego a 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;

Configuración

Variable	Predeterminado	Descripción
TABLEBRIDGE_DATA_DIR	.	Directorio de archivos a exponer (el límite del entorno aislado)
TABLEBRIDGE_MAX_ROWS	1000	Máximo de filas devueltas por consulta/vista previa
TABLEBRIDGE_RECURSIVE	1	Escanear también subdirectorios

Formatos admitidos: .csv, .tsv, .parquet, .json, .ndjson.

Modelo de seguridad

1. Aislado a TABLEBRIDGE_DATA_DIR — solo se cargan los archivos que están dentro.
2. Materializado en un DuckDB en memoria, luego se deshabilita el acceso externo al sistema de archivos — las consultas no pueden alcanzar otras rutas.
3. SQL validado — solo una declaración de solo lectura; se rechazan escrituras y funciones de lectura de archivos sin procesar.

Desarrollo

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

Consulta CONTRIBUTING.md.

Licencia

MIT © Michael Tierney