tablebridge

tablebridge

Transforme uma pasta de arquivos CSV / Parquet / JSON em uma única fonte consultável via SQL para seu agente de IA.

Pequenas empresas não têm um data warehouse — elas têm uma pasta cheia de exportações: customers.csv, o orders.xlsx do mês passado, um regions.json que alguém enviou por e-mail. tablebridge é um servidor MCP que aponta o DuckDB para essa pasta, expõe cada arquivo como uma tabela SQL e permite que seu agente execute SQL somente leitura — incluindo JOINs entre arquivos — para responder perguntas sobre todos eles de uma vez. Planilhas espalhadas se tornam uma única fonte de verdade consultável.

É somente leitura e isolado (sandbox): os arquivos são carregados em um banco de dados em memória, o diretório de dados é a única coisa que ele pode ver, e as consultas são validadas para que um agente não possa gravar, escapar para outros caminhos ou chamar funções brutas de arquivo.

---

Por que você vai querer isso

• 🔗 Uma única fonte sobre muitos arquivos. Faça JOIN de orders.csv com customers.csv e regions.json em uma única consulta — sem ETL, sem precisar subir um banco de dados.
• 🦆 Com tecnologia DuckDB. SQL analítico rápido sobre CSV, TSV, Parquet, JSON/NDJSON.
• 🔒 Seguro por design. Os arquivos são materializados em memória; as consultas são validadas como somente leitura; funções brutas de acesso a arquivos e caminhos fora do sandbox são rejeitados.
• 🤖 Amigável para agentes. list_sources → describe → query é um fluxo natural que o agente pode seguir sozinho.
• 🪶 Duas dependências (mcp, duckdb), totalmente tipado e testado.

Instalação

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

O Tablebridge usa a API FastMCP do MCP Python SDK 1.x. Sua faixa de dependências permanece abaixo do SDK 2 até que o servidor seja migrado para essa 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" }
    }
  }
}

Executar com Docker

Um Dockerfile está incluído. O servidor fala MCP via stdio. Monte a pasta que você deseja consultar em /data (somente leitura é suficiente) e execute interativamente (-i):

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

Ferramentas

Ferramenta	Descrição
list_sources	Liste as tabelas (uma por arquivo de dados) com contagens de colunas — comece aqui
describe	Colunas e tipos de uma tabela
preview	Primeiras N linhas de uma tabela
query	Execute SQL somente leitura (dialeto DuckDB) nas tabelas, incluindo JOINs
refresh	Re-escaneie o diretório de dados em busca de arquivos adicionados/alterados
server_info	Configuração efetiva (diretório de dados, limite de linhas, formatos suportados)

Exemplo

Com uma pasta contendo customers.csv, orders.csv e regions.json:

Você: Quais são meus 3 principais clientes por gasto total e em qual região eles estão?

Agente: (chama list_sources, depois 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;

Configuração

Variável	Padrão	Descrição
TABLEBRIDGE_DATA_DIR	.	Diretório de arquivos a expor (o limite do sandbox)
TABLEBRIDGE_MAX_ROWS	1000	Máximo de linhas retornadas por consulta/pré-visualização
TABLEBRIDGE_RECURSIVE	1	Escanear também subdiretórios

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

Modelo de segurança

1. Isolado (sandbox) em TABLEBRIDGE_DATA_DIR — apenas arquivos dentro dele são carregados.
2. Materializado em um DuckDB em memória; depois, o acesso externo ao sistema de arquivos é desabilitado — as consultas não podem alcançar outros caminhos.
3. SQL validado — apenas uma única instrução somente leitura; gravações e funções brutas de leitura de arquivos são rejeitadas.

Desenvolvimento

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

Veja CONTRIBUTING.md.

Licença

MIT © Michael Tierney