Servidor MCP do GizmoSQL
Dê ao Claude Desktop, Claude Code e a qualquer cliente MCP acesso ao seu servidor GizmoSQL. Faça perguntas em linguagem natural; o Claude explora o esquema e executa SQL via Apache Arrow Flight SQL. Somente leitura por padrão, com limites de linhas e tempo aplicados pelo servidor, e credenciais que nunca saem da sua máquina.
O servidor MCP funciona na sua máquina e usa Arrow Flight SQL para conversar com o servidor GizmoSQL configurado, por meio do cliente oficial Node.js e do driver ADBC nativo do GizmoSQL.
Em produção na Vaden Automotive
A equipe da Vaden faz perguntas de negócios em linguagem natural pelo Claude, que consulta o GizmoSQL pelo servidor MCP do GizmoSQL.
“At Vaden Automotive Group, GizmoData in our Cloud has changed how quickly we get from a question to an answer. Its MCP server connects our data directly to AI, so our team can ask questions in natural language and get real analysis through simple prompts, then turn those results into artifacts and working applications in a fraction of the time it used to take. That makes prototyping effortless and gives us rapid insights without long development cycles. It’s fast, lightweight, and delivers true business intelligence across our entire dealership group without the large price tag. GizmoSQL has become a core part of how we see and run our business.”Tradução livre: “No Vaden Automotive Group, a GizmoData na nossa nuvem mudou a rapidez com que passamos de uma pergunta a uma resposta. O servidor MCP dela conecta nossos dados diretamente à IA, então nossa equipe pode fazer perguntas em linguagem natural e obter análises reais com prompts simples, e depois transformar esses resultados em artefatos e aplicações funcionais em uma fração do tempo que isso levava. Isso torna a prototipagem descomplicada e nos dá insights rápidos sem longos ciclos de desenvolvimento. É rápido, leve e entrega inteligência de negócios de verdade em todo o nosso grupo de concessionárias, sem o preço alto. O GizmoSQL se tornou parte central de como enxergamos e conduzimos o nosso negócio.”
Faça uma pergunta aos seus dados
O Claude descobre catálogos, esquemas e tabelas sozinho, escreve SQL, executa e apresenta os resultados. Alguns prompts que funcionam desde o início:
“Quais tabelas do esquema sales têm a coluna customer_id e como elas se relacionam?”
“Mostre a receita por região nos últimos quatro trimestres, em uma tabela.”
“Explique o plano desta consulta e diga por que ela está lenta.”
“Compare a contagem de linhas de orders em produção e desenvolvimento.”
As ferramentas disponíveis para o Claude
Um conjunto pequeno e focado para explorar esquemas e consultar dados. Todas as ferramentas, exceto as de conexão, também aceitam o argumento opcional connection .
| Ferramenta | O que faz |
|---|---|
| list_catalogs | Catálogos (bancos associados) visíveis para o usuário. |
| list_schemas(catalog?) | Esquemas, opcionalmente dentro de um catálogo. |
| list_tables(catalog?, schema?, like?) | Tabelas e visões com seu tipo; like é um padrão SQL LIKE. |
| describe_table(table, schema?, catalog?) | Colunas, tipos, possibilidade de valores nulos, restrições e estimativa de contagem de linhas. |
| use_schema(catalog?, schema?) | Define catálogo/esquema padrão da sessão (DuckDB USE) para resolver nomes não qualificados. |
| run_query(sql, params?, max_rows?) | Executa uma consulta e retorna uma tabela Markdown e JSON estruturado, limitado a max_rows. |
| explain_query(sql) | O plano DuckDB EXPLAIN, sem executar a consulta. |
| server_info() | Versões do GizmoSQL e DuckDB, URI de conexão com dados sensíveis ocultos, limites efetivos e versão da extensão. |
| list_connections() / use_connection(name) | Veja os servidores GizmoSQL configurados (nunca as credenciais) e altere o padrão para o restante da conversa. |
| execute_statement(sql, params?) | DML/DDL com contagem de linhas afetadas. Registrado apenas quando GIZMOSQL_ALLOW_WRITES=true. |
| login_sso(wait_seconds?) | Login OAuth/SSO no navegador. Registrado apenas quando GIZMOSQL_ENABLE_SSO=true. |
Também disponibiliza um modelo de recurso, gizmosql://{connection}/schema/{catalog}/{schema}/{table}, que retorna o DDL de uma tabela ou visão.
Instale em um minuto
Escolha seu cliente. Todas as configurações são variáveis de ambiente (a tela de configurações do Claude Desktop usa os mesmos nomes).
- Baixe o pacote mais recente, gizmosql-mcp.mcpb (soma de verificação).
- Clique duas vezes no arquivo ou, no Claude Desktop, abra Settings → Extensions → Advanced settings → Install Extension… e selecione-o.
- Preencha host, porta, credenciais e limites. As credenciais são marcadas como sensíveis e armazenadas no chaveiro do sistema operacional.
- Em uma conversa, abra o menu + , escolha Connectorse ative GizmoSQL.
Não é necessário instalar Node.js: o Claude Desktop executa a extensão com seu runtime integrado, e o pacote inclui o driver nativo para macOS (Apple Silicon e Intel), Linux (x64 e arm64) e Windows x64.
Feito para conectar um LLM a dados reais
Controles no servidor, limites aplicados pelo próprio GizmoSQL e nenhum acesso ao seu sistema de arquivos ou a endpoints de rede além do host GizmoSQL configurado.
Somente leitura por padrão
Um controle SQL classifica cada instrução e permite apenas SELECT, WITH … SELECT, SHOW, DESCRIBE, SUMMARIZE, EXPLAIN e USE. DML, COPY, ATTACH, INSTALL, LOAD, SET e entradas com múltiplas instruções são rejeitadas, a menos que você habilite gravações explicitamente.
Limite de linhas aplicado pelo servidor
As leituras executam SELECT * FROM (your query) LIMIT max_rows + 1 e retornam em lotes que param no limite (500 linhas por padrão). Nada é obtido integralmente para depois ser cortado no cliente.
Limite de tempo aplicado pelo servidor
Cada instrução recebe um 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.
As credenciais nunca vazam
Senhas e tokens nunca aparecem na saída das ferramentas, em server_info ou em mensagens de erro. O Claude Desktop os armazena no chaveiro do sistema operacional.
Consultas parametrizadas
run_query aceita um array params vinculado a marcadores ?. Os valores chegam ao servidor como dados Arrow tipados, sem interpolação no texto SQL.
Executado na sua máquina
O servidor funciona localmente e se conecta diretamente ao host GizmoSQL configurado; redes privadas via VPN funcionam normalmente. Não coleta telemetria nem acessa outro endpoint de rede.
O limite real é o usuário GizmoSQL
Trate o controle SQL como defesa em profundidade. Com autenticação por usuário/senha, toda sessão tem o papel admin e, portanto, para qualquer uso além de um sandbox, emita um JWT GizmoSQL com o papel integrado readonly e configure o usuário token com o JWT como senha: o próprio servidor permitirá apenas SELECT. GizmoSQL Enterprise adiciona permissões por catálogo de leitura/gravação/nenhum acesso no token, além de instrumentação de sessões para você ver exatamente o que o agente executou.
Vários servidores, uma conversa
Configure produção, desenvolvimento e homologação lado a lado. O Claude alterna com use_connection ou indica uma conexão por chamada; assim, “compare orders em produção e desenvolvimento” é um único prompt.
Extensão Claude Desktop
A tela de configurações tem os campos Connection 2 e Connection 3 — cada um com host, credenciais, opções TLS e catálogo/esquema padrão próprios. Deixe o host de um campo vazio para desativá-lo.
Variáveis de ambiente
Liste os nomes em GIZMOSQL_CONNECTIONS e defina cada um com as mesmas variáveis prefixadas pelo nome em maiúsculas. Qualquer número de servidores.
GIZMOSQL_CONNECTIONS=prod,dev-eu
GIZMOSQL_PROD_HOST=gizmosql.prod.example.com
GIZMOSQL_PROD_USERNAME=token
GIZMOSQL_PROD_PASSWORD=<jwt>
GIZMOSQL_DEV_EU_HOST=gizmosql.dev.example.com
GIZMOSQL_DEV_EU_USERNAME=analyst
GIZMOSQL_DEV_EU_PASSWORD=<password>Ainda não tem servidor GizmoSQL? Experimente com dois comandos
Inicie um servidor GizmoSQL com tabelas TPC-H de demonstração e cadastre-o no Claude Code. Pergunte ao Claude: “quais tabelas existem e qual região tem mais clientes?”
1. Inicie o servidor
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:latest2. Cadastre-o no Claude Code
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-mcpA imagem Docker usa um certificado autoassinado; por isso, GIZMOSQL_TLS_SKIP_VERIFY=true. Use o mesmo host, porta e credenciais nas configurações da extensão Claude Desktop.
Prefere instalar o servidor nativamente? Veja a página de instalação do GizmoSQL →
O que é o servidor MCP do GizmoSQL?
É um servidor Model Context Protocol (MCP) e uma extensão Claude Desktop para o GizmoSQL, o servidor Apache Arrow Flight SQL baseado em DuckDB. Permite que Claude Desktop, Claude Code e outros clientes MCP explorem esquemas e executem SQL em um servidor GizmoSQL acessível pela sua máquina. É gratuito e de código aberto sob Apache-2.0.
É seguro conectar um LLM ao meu banco de dados?
O servidor é somente leitura por padrão: um controle SQL rejeita qualquer operação que não seja leitura, e gravações só são possíveis com GIZMOSQL_ALLOW_WRITES=true. Limites de linhas e tempo são aplicados no servidor. O limite real de segurança é o usuário GizmoSQL utilizado na conexão: emita um JWT GizmoSQL com o papel readonly (usuário token, senha = JWT), e o próprio servidor permitirá apenas SELECT. O GizmoSQL Enterprise adiciona permissões de leitura/gravação/nenhum acesso por catálogo no token.
Funciona com Claude Code?
Sim. Execute claude mcp add gizmosql com as variáveis de ambiente GIZMOSQL_* e npx -y @gizmodata/gizmosql-mcp como comando. Adicione -s user para disponibilizar o servidor em todos os projetos. É necessário Node.js 22 ou mais recente ao executar por npx.
Preciso instalar Node.js para a extensão Claude Desktop?
Não. O pacote .mcpb usa o runtime Node incluído no Claude Desktop e traz o driver ADBC nativo do GizmoSQL para macOS (Apple Silicon e Intel), Linux (x64 e arm64) e Windows x64. Baixe o pacote, clique duas vezes nele ou instale em Settings e preencha as configurações de conexão.
Ele acessa um servidor GizmoSQL em rede privada?
Sim. O servidor é executado na sua máquina e se conecta diretamente; qualquer destino acessível pela sua VPN, túnel SSH ou kubectl port-forward funciona. Aponte para localhost ao encaminhar uma porta.
Posso usar um cliente MCP remoto, como um conector personalizado do Claude.ai?
Sim. Inicie o mesmo servidor com --transport http para atender por Streamable HTTP em /mcp (e pelo endpoint /healthz). Defina GIZMOSQL_MCP_BEARER_TOKEN para exigir o cabeçalho Authorization: Bearer em cada solicitação e coloque o endpoint atrás de TLS antes de expô-lo além de localhost.
Uma conversa pode acessar vários servidores GizmoSQL?
Sim. A extensão Claude Desktop tem espaço para até três conexões, e as variáveis de ambiente permitem qualquer número via GIZMOSQL_CONNECTIONS. Cada ferramenta aceita um argumento connection opcional, e use_connection altera o padrão; assim, um prompt como “compare a contagem de linhas de orders em produção e desenvolvimento” funciona em uma única conversa.