Apresentamos o servidor MCP do GizmoSQL: converse com seus dados DuckDB pelo Claude

Ontem lançamos o gizmosql-mcp: um servidor Model Context Protocol e uma extensão do Claude Desktop para o GizmoSQL, o servidor Apache Arrow Flight SQL construído sobre o DuckDB. Instale-o, aponte para um servidor GizmoSQL acessível pelo seu notebook e o Claude poderá explorar o esquema, escrever e executar SQL e apresentar a resposta.

Ele é gratuito e de código aberto (Apache-2.0), funciona com Claude Desktop, Claude Code e qualquer outro cliente MCP, e foi projetado desde o primeiro commit em torno de uma pergunta: o que é preciso para conectar um LLM a um banco de dados real com segurança?

Por que um servidor MCP para o GizmoSQL?

Boa parte do valor do GizmoSQL está em transformar o DuckDB em um servidor compartilhado, concorrente e autenticado, em vez de uma biblioteca dentro do processo. É exatamente o que assistentes de IA precisam. Um agente não deveria copiar arquivos Parquet de um lado para outro nem abrir um arquivo DuckDB bloqueado por outro processo; deveria se conectar a um servidor com credenciais e executar consultas como qualquer outro cliente.

MCP é a forma padrão de disponibilizar ferramentas a um assistente. Por isso, o caminho natural foi criar um servidor MCP com ferramentas para "examinar o esquema" e "executar esta consulta", usando Arrow Flight SQL para falar com o GizmoSQL. Agora, uma conversa como esta funciona diretamente:

"Quais tabelas do esquema de vendas têm uma coluna customer_id e como se relacionam? Depois, mostre a receita por região nos últimos quatro trimestres."

O Claude chama list_tables e describe_table algumas vezes, escreve as junções, chama run_query e formata o resultado. Você não precisa sair da conversa.

O que o Claude recebe

O conjunto de ferramentas é pequeno de propósito:

Exploração do esquema: list_catalogs, list_schemas, list_tables (com filtro LIKE) e describe_table, que retorna colunas, tipos, possibilidade de nulos, restrições e estimativa de linhas. use_schema define o catálogo e o esquema padrão da sessão para resolver nomes de tabelas sem qualificação.
Consultas: run_query retorna uma tabela Markdown e JSON estruturado, limitados por max_rows. explain_query retorna o plano EXPLAIN do DuckDB sem executar nada.
Inspeção: server_info informa as versões do GizmoSQL e do DuckDB, a URI de conexão com dados sensíveis ocultos, os limites efetivos e o usuário com o qual o servidor está conectado.
Vários servidores: list_connections e use_connection; todas as demais ferramentas aceitam o argumento opcional connection. "Compare a contagem de linhas de pedidos em produção e desenvolvimento" cabe em um único prompt.
Recursos opcionais: execute_statement (DML/DDL) só aparece quando você define GIZMOSQL_ALLOW_WRITES=true, e login_sso apenas quando o SSO está habilitado.

Há também um modelo de recurso, gizmosql://{connection}/schema/{catalog}/{schema}/{table}, que retorna o DDL de uma tabela.

As consultas podem ser parametrizadas. run_query recebe um array params associado a marcadores ?, e os valores chegam ao servidor como dados Arrow tipados, nunca como texto SQL interpolado. Esta é a chamada que fizemos em um contêiner novo do GizmoSQL v1.38.1 ao escrever este artigo, junto com o texto exato retornado:

{
  "sql": "SELECT ?::INTEGER AS n, version() AS duckdb",
  "params": [42],
  "max_rows": 5
}

A ferramenta retorna as linhas em uma tabela Markdown (lida diretamente pelo Claude), seguida de uma linha de resumo. A resposta renderizada fica assim:

n	duckdb
42	v1.5.5

1 linha retornada · 301 ms

Somente leitura por padrão — e por que essa não é a fronteira de segurança

Na configuração padrão, o servidor recusa tudo que não seja leitura. Uma proteção SQL classifica cada instrução e só permite SELECT, WITH … SELECT, FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE, EXPLAIN, PRAGMA de leitura e USE. CTEs que terminam em DML, COPY, ATTACH, INSTALL, LOAD, SET, CALL, transações e entradas com múltiplas instruções são rejeitadas.

Outras garantias são impostas pelo servidor, sem depender da confiança no cliente:

Limite de linhas: as leituras são executadas como SELECT * FROM (your query) LIMIT max_rows + 1 e transmitidas em lotes que param no limite (500 linhas por padrão). Nenhum resultado é buscado inteiro para depois ser recortado.
Tempo limite: cada instrução recebe um tempo limite por consulta via SET gizmosql.query_timeout na sessão (60 s por padrão), com um prazo no cliente como proteção adicional para cancelar a instrução.
Ocultação de dados sensíveis: credenciais nunca aparecem na saída das ferramentas, em server_info ou nas mensagens de erro. O Claude Desktop as armazena no chaveiro do sistema operacional.
Execução local: o servidor roda na sua máquina, conversa apenas com o host GizmoSQL configurado, não tem ferramentas de acesso ao sistema de arquivos local e não coleta telemetria.

É preciso deixar claro o papel dessa proteção: defesa em profundidade, não a fronteira de segurança. A fronteira são os privilégios do usuário GizmoSQL usado na conexão. Com autenticação por usuário e senha, toda sessão GizmoSQL recebe o papel admin. Fora de um ambiente de testes isolado, gere um JWT GizmoSQL com o papel integrado readonly e configure o usuário token com o JWT como senha; o próprio GizmoSQL permitirá apenas SELECT, independentemente do que o cliente enviar. O GizmoSQL Enterprise vai além, com permissões de leitura, gravação ou nenhum acesso por catálogo no token, além de instrumentação das sessões para mostrar exatamente o que o agente executou e quando.

Instale em um minuto

Claude Desktop

Baixe gizmosql-mcp.mcpb, clique duas vezes no arquivo (ou use Settings → Extensions → Advanced settings → Install Extension…), preencha host, porta e credenciais e ative GizmoSQL no menu + → Connectors de uma conversa. Não é preciso instalar Node.js: o pacote usa o ambiente de execução do próprio Claude Desktop e inclui o driver ADBC nativo do GizmoSQL para macOS (Apple Silicon e Intel), Linux (x64 e arm64) e Windows x64.

Claude Code

claude mcp add gizmosql \
  -e GIZMOSQL_HOST=gizmosql.internal.example.com \
  -e GIZMOSQL_PORT=31337 \
  -e GIZMOSQL_USERNAME=analyst \
  -e GIZMOSQL_PASSWORD='your-password' \
  -- npx -y @gizmodata/gizmosql-mcp

Adicione -s user para disponibilizá-lo em todos os projetos. Qualquer outro cliente MCP que aceite uma definição de servidor stdio funciona da mesma forma, com npx -y @gizmodata/gizmosql-mcp como comando e as variáveis GIZMOSQL_* no ambiente.

Clientes remotos por Streamable HTTP

O mesmo servidor pode atender por Streamable HTTP clientes que se conectam pela rede, como um conector personalizado do Claude.ai. Defina um token bearer, proteja o serviço com TLS e aponte o conector para /mcp:

GIZMOSQL_HOST=gizmosql.internal.example.com \
GIZMOSQL_USERNAME=analyst GIZMOSQL_PASSWORD='your-password' \
GIZMOSQL_MCP_BEARER_TOKEN='a-long-random-secret' \
npx -y @gizmodata/gizmosql-mcp --transport http --host 0.0.0.0 --port 3000

Experimente com um servidor de demonstração

Ainda não tem um servidor GizmoSQL? Isto inicia um com tabelas de demonstração TPC-H e o registra no Claude Code. A imagem Docker usa um certificado autoassinado, daí o GIZMOSQL_TLS_SKIP_VERIFY=true.

docker run --name gizmosql --detach --rm --tty --init \
  --publish 31337:31337 \
  --env TLS_ENABLED="1" \
  --env GIZMOSQL_USERNAME="gizmosql_user" \
  --env GIZMOSQL_PASSWORD="gizmosql_password" \
  --env INIT_SQL_COMMANDS="CALL dbgen(sf=0.01);" \
  --pull always \
  gizmodata/gizmosql:latest

claude mcp add gizmosql \
  -e GIZMOSQL_HOST=localhost \
  -e GIZMOSQL_PORT=31337 \
  -e GIZMOSQL_USERNAME=gizmosql_user \
  -e GIZMOSQL_PASSWORD=gizmosql_password \
  -e GIZMOSQL_TLS_SKIP_VERIFY=true \
  -- npx -y @gizmodata/gizmosql-mcp

Depois, peça ao Claude: "Quais tabelas existem e qual região tem mais clientes?"

Como funciona por dentro

A conexão usa a biblioteca Node.js oficial @gizmodata/gizmosql-client (a mesma do GizmoSQL UI) e o driver ADBC nativo do GizmoSQL. Os resultados permanecem colunares do DuckDB até a resposta da ferramenta. A extensão é um único pacote .mcpb com o driver de cada plataforma; o pacote npm baixa o driver da sua plataforma na primeira instalação.

Como o servidor se conecta diretamente da sua máquina, redes privadas por VPN, túneis SSH e kubectl port-forward funcionam: basta apontá-lo para localhost ao criar um túnel de porta.

Próximos passos

OAuth no próprio endpoint HTTP é o próximo passo natural para conectores remotos (o SSO no servidor GizmoSQL já funciona via login_sso). Também queremos saber quais prompts você mais usa. Conte para nós no Slack da comunidade GizmoData ou abra uma issue no GitHub.

Página do produto: servidor MCP do GizmoSQL →