GizmoSQL MCP Server
Give Claude Desktop, Claude Code, and any MCP client a window into your GizmoSQL server. Ask questions in plain English; Claude explores the schema and runs the SQL over Apache Arrow Flight SQL. Read-only by default, with row caps and timeouts the server enforces, and credentials that never leave your machine.
The MCP server runs on your machine and speaks Arrow Flight SQL to the GizmoSQL server you configure, using the official Node.js client and the native GizmoSQL ADBC driver.
Ask Your Data a Question
Claude discovers catalogs, schemas, and tables on its own, writes the SQL, runs it, and reads the results back to you. Some prompts that work out of the box:
“Which tables in the sales schema have a customer_id column, and how are they related?”
“Show me revenue by region for the last four quarters, as a table.”
“Explain the query plan for this statement and tell me why it is slow.”
“Compare the row count of orders on prod and dev.”
The Tools Claude Gets
A small, focused toolset for schema exploration and querying. Every tool except the connection tools also accepts an optional connection argument.
| Tool | What it does |
|---|---|
| list_catalogs | Catalogs (attached databases) visible to the user. |
| list_schemas(catalog?) | Schemas, optionally within one catalog. |
| list_tables(catalog?, schema?, like?) | Tables and views with their type; like is a SQL LIKE pattern. |
| describe_table(table, schema?, catalog?) | Columns, types, nullability, constraints, and an estimated row count. |
| use_schema(catalog?, schema?) | Sets the session's default catalog/schema (DuckDB USE) so unqualified names resolve. |
| run_query(sql, params?, max_rows?) | Runs a query and returns a Markdown table plus structured JSON, capped at max_rows. |
| explain_query(sql) | The DuckDB EXPLAIN plan, without executing the query. |
| server_info() | GizmoSQL and DuckDB versions, the redacted connection URI, effective limits, and the extension version. |
| list_connections() / use_connection(name) | See the configured GizmoSQL servers (never credentials) and switch the default for the rest of the chat. |
| execute_statement(sql, params?) | DML/DDL with an affected-row count. Only registered when GIZMOSQL_ALLOW_WRITES=true. |
| login_sso(wait_seconds?) | Browser-based OAuth/SSO sign-in. Only registered when GIZMOSQL_ENABLE_SSO=true. |
It also exposes a resource template, gizmosql://{connection}/schema/{catalog}/{schema}/{table}, that returns the DDL of a table or view.
Install in a Minute
Pick your client. All settings are environment variables (the Claude Desktop settings screen maps onto the same names).
- Download the latest bundle, gizmosql-mcp.mcpb (checksum).
- Double-click the file, or in Claude Desktop open Settings → Extensions → Advanced settings → Install Extension… and pick it.
- Fill in the host, port, credentials, and limits. Credentials are marked sensitive and stored in your operating system's keychain.
- In a chat, open the + menu, choose Connectors, and turn on GizmoSQL.
No Node.js install is needed: Claude Desktop runs the extension with its bundled runtime, and the native driver for macOS (Apple Silicon and Intel), Linux (x64 and arm64), and Windows x64 is inside the bundle.
Built for Pointing an LLM at Real Data
Guardrails in the server, limits enforced by GizmoSQL itself, and nothing that touches your filesystem or any network endpoint except the GizmoSQL host you configure.
Read-only by default
A SQL guard classifies every statement and only lets SELECT, WITH … SELECT, SHOW, DESCRIBE, SUMMARIZE, EXPLAIN, and USE through. DML, COPY, ATTACH, INSTALL, LOAD, SET, and multi-statement input are rejected unless you explicitly enable writes.
Server-enforced row cap
Reads run as SELECT * FROM (your query) LIMIT max_rows + 1 and stream back in batches that stop at the cap (default 500 rows). Nothing is fetched whole and sliced client-side.
Server-enforced timeout
Each statement gets a per-query timeout via SET gizmosql.query_timeout on the session (default 60 s), with a client-side deadline as a backstop that cancels the statement.
Credentials never leak
Passwords and tokens never appear in tool output, server_info, or error messages. Claude Desktop stores them in your operating-system keychain.
Parameterised queries
run_query accepts a params array bound to ? placeholders. Values travel to the server as typed Arrow data, never interpolated into SQL text.
Runs on your machine
The server runs locally and connects directly to the GizmoSQL host you configure, so private networks over VPN just work. It collects no telemetry and touches no other network endpoint.
The real boundary is the GizmoSQL user
Treat the SQL guard as defense in depth. With username/password authentication every session has the admin role, so for anything beyond a sandbox mint a GizmoSQL JWT with the built-in readonly role and configure username token with the JWT as the password: the server itself will then permit only SELECT. GizmoSQL Enterprise adds per-catalog read/write/none permissions in the token, plus session instrumentation so you can see exactly what the agent ran.
Several Servers, One Conversation
Configure prod, dev, and staging side by side. Claude switches with use_connection or names a connection per call, so “compare orders on prod and dev” is a single prompt.
Claude Desktop extension
The settings screen has Connection 2 and Connection 3 slots, each with its own host, credentials, TLS flags, and default catalog/schema. Leave a slot's host blank to disable it.
Environment variables
List names in GIZMOSQL_CONNECTIONS and define each with the same variables prefixed by the upper-cased name. Any number of servers.
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>No GizmoSQL Server Yet? Try It in Two Commands
Start a GizmoSQL server with TPC-H demo tables, then register it with Claude Code. Ask Claude “what tables are there and which region has the most customers?”
1. Start the server
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. Register it with 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-mcpThe Docker image uses a self-signed certificate, hence GIZMOSQL_TLS_SKIP_VERIFY=true. Use the same host, port, and credentials in the Claude Desktop extension settings.
Prefer a native install of the server? See the GizmoSQL install page →
What is the GizmoSQL MCP server?
It is a Model Context Protocol (MCP) server and Claude Desktop extension for GizmoSQL, the Apache Arrow Flight SQL server built on DuckDB. It lets Claude Desktop, Claude Code, and any other MCP client explore your schema and run SQL against a GizmoSQL server you can reach from your machine. It is free and open source under Apache-2.0.
Is it safe to point an LLM at my database?
The server is read-only by default: a SQL guard rejects anything that is not a read, and writes are only possible when you set GIZMOSQL_ALLOW_WRITES=true. Row caps and query timeouts are enforced server-side. The real security boundary is the GizmoSQL user the server connects as: mint a GizmoSQL JWT with the readonly role (username token, password = the JWT) and the server itself will only permit SELECT. GizmoSQL Enterprise adds per-catalog read/write/none permissions in the token.
Does it work with Claude Code?
Yes. Run claude mcp add gizmosql with the GIZMOSQL_* environment variables and npx -y @gizmodata/gizmosql-mcp as the command. Add -s user to make the server available in every project. Node.js 22 or newer is required when running through npx.
Do I need to install Node.js for the Claude Desktop extension?
No. The .mcpb bundle runs on the Node runtime that ships inside Claude Desktop, and it includes the native GizmoSQL ADBC driver for macOS (Apple Silicon and Intel), Linux (x64 and arm64), and Windows x64. Download the bundle, double-click it or install it from Settings, and fill in the connection settings.
Can it reach a GizmoSQL server on a private network?
Yes. The server runs on your machine and connects directly, so anything you can reach over your VPN, an SSH tunnel, or a kubectl port-forward works. Point it at localhost when you tunnel a port.
Can I use it with a remote MCP client, such as a Claude.ai custom connector?
Yes. Start the same server with --transport http and it listens for Streamable HTTP at /mcp (plus a /healthz endpoint). Set GIZMOSQL_MCP_BEARER_TOKEN so every request must carry an Authorization: Bearer header, and put the endpoint behind TLS before exposing it beyond localhost.
Can one chat talk to several GizmoSQL servers?
Yes. The Claude Desktop extension has slots for up to three connections, and environment variables support any number via GIZMOSQL_CONNECTIONS. Every tool accepts an optional connection argument, and use_connection switches the default, so a prompt like "compare row counts of orders on prod and dev" works in one conversation.