gizmosql-mcp

A Model Context Protocol server and Claude Desktop extension for GizmoSQL, the 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 (including private networks over VPN).

Connectivity uses the official @gizmodata/gizmosql-client and the native GizmoSQL ADBC driver, which the extension bundles for macOS (Apple Silicon and Intel), Linux (x64 and arm64) and Windows x64.

Tools

| Tool | What it does | | --- | --- | | list_connections() | Configured GizmoSQL connections and which one is current (never credentials) | | use_connection(name) | Makes a connection the default for subsequent calls | | list_catalogs | Catalogs (attached databases) visible to the user | | list_schemas(catalog?, include_system?) | Schemas, optionally in one catalog; system schemas (information_schema, pg_catalog, pg_toast, pg_temp_*) are hidden unless include_system is true | | 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, estimated row count | | use_schema(catalog?, schema?) | Sets the session's default catalog/schema (DuckDB USE) for unqualified table names | | run_query(sql, params?, max_rows?) | Runs a query; returns a Markdown table plus structured JSON, capped at max_rows | | explain_query(sql) | DuckDB EXPLAIN plan without executing | | execute_statement(sql, params?) | DML/DDL with affected-row count. Only registered when writes are enabled | | server_info() | GizmoSQL/DuckDB versions, redacted connection URI, effective limits, extension version | | login_sso(wait_seconds?) | Browser-based OAuth/SSO sign-in. Only registered when SSO is enabled |

Every tool except list_connections and use_connection also accepts an optional connection argument naming one of the configured servers (see Multiple connections).

It also exposes a resource template, gizmosql://{connection}/schema/{catalog}/{schema}/{table}, that returns the DDL of a table or view.

Query parameters

run_query and execute_statement accept a params array bound positionally to ? (or $1, $2, ...) placeholders. Values travel to the server as typed Arrow data, never as interpolated SQL text, so use placeholders for any literal that comes from user input or from data returned by an earlier query.

• Plain JSON values: string, number, boolean, null. Strings in ISO-8601 date or timestamp form (2024-01-02, 2024-01-02T03:04:05Z) are bound as timestamps.
• Explicit types: {"type": "bigint", "value": "9223372036854775807"}, {"type": "string", "value": "2024-01-02"} (keep a date-looking string as text), {"type": "binary", "value": "<base64>"}, plus date, timestamp, number, boolean and null.
• A placeholder whose type the server cannot infer from context, such as SELECT ?, must be cast: SELECT ?::INTEGER.

Example call:

{
  "sql": "SELECT id, name FROM customers WHERE created_at >= ? AND region = ? LIMIT 20",
  "params": ["2024-01-01", "EMEA"]
}

Installation

Quick links: latest .mcpb download · npm package · all releases

Claude Desktop extension (.mcpb)

1. Download the latest bundle: gizmosql-mcp.mcpb (checksum: gizmosql-mcp.mcpb.sha256). Every release also carries a versioned copy, gizmosql-mcp-<version>.mcpb, on the Releases page.
2. Either double-click the file, or in Claude Desktop open Settings → Extensions → Advanced settings → Install Extension… and pick the file.
3. Fill in the settings (host, port, credentials, limits). Credentials are marked sensitive and are stored in your operating system's keychain.
4. In a chat, open the + menu, choose Connectors and make sure GizmoSQL is turned on. Tools become available immediately.

No Node.js installation is needed: Claude Desktop runs the extension with its bundled runtime (Node 24 in current builds), and the native driver for your platform is inside the bundle.

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

Use -s user to make it available in every project. Node.js 22 or newer is required when running through npx; the client downloads the native driver for your platform on first install.

claude_desktop_config.json (manual JSON)

{
  "mcpServers": {
    "gizmosql": {
      "command": "npx",
      "args": ["-y", "@gizmodata/gizmosql-mcp"],
      "env": {
        "GIZMOSQL_HOST": "gizmosql.internal.example.com",
        "GIZMOSQL_PORT": "31337",
        "GIZMOSQL_USERNAME": "analyst",
        "GIZMOSQL_PASSWORD": "your-password"
      }
    }
  }
}

Streamable HTTP (remote connector)

The same server can listen over Streamable HTTP for MCP clients that connect over the network, such as a Claude.ai custom connector. The MCP endpoint is /mcp; /healthz answers health checks. Put it behind TLS (an ingress or reverse proxy) before exposing it beyond localhost. Requests are authenticated in one of two ways.

OAuth (recommended). Any OpenID Connect provider that issues signed JWT access tokens works: Microsoft Entra ID, Okta (custom authorization server), Auth0, Keycloak, Cognito, Clerk. The server is an OAuth 2.1 resource server: it verifies each bearer token against the provider's JWKS (issuer, audience, signature, expiry) and serves the RFC 9728 metadata at /.well-known/oauth-protected-resource[/mcp] so clients find the provider on their own. The token is never forwarded; the GizmoSQL connection uses the configured service credentials.

GIZMOSQL_HOST=gizmosql.internal.example.com \
GIZMOSQL_USERNAME=mcp_service GIZMOSQL_PASSWORD='service-password' \
GIZMOSQL_MCP_PUBLIC_URL=https://mcp.example.com/mcp \
GIZMOSQL_MCP_OAUTH_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0 \
GIZMOSQL_MCP_OAUTH_AUDIENCE=<application-client-id> \
GIZMOSQL_MCP_OAUTH_SCOPES='https://mcp.example.com/mcp/access_as_user openid profile email offline_access' \
GIZMOSQL_MCP_OAUTH_TOKEN_PROXY=true \
GIZMOSQL_MCP_OAUTH_AUTHORIZED_EMAILS='*@example.com' \
npx -y @gizmodata/gizmosql-mcp --transport http --host 0.0.0.0 --port 3000

Then add https://mcp.example.com/mcp as a custom connector in Claude (Customize > Connectors). Claude sends that URL as the OAuth resource, discovers the provider from the metadata, runs the authorization-code flow with PKCE, and retries with the token. Each tool call is logged with the caller's identity, and server_info reports it as authenticated_user.

Claude requests exactly the scopes named in GIZMOSQL_MCP_OAUTH_SCOPES (they are sent in the WWW-Authenticate challenge and as scopes_supported), so include offline_access alongside the API scope: it is what makes the provider issue a refresh token, which Claude uses to renew the access token on its own (reactively on a 401, and shortly before expiry). The server warns at startup when the scope list lacks it and logs every rejected token with the reason (unauthorized: "exp" claim timestamp check failed).

Token proxy (required for Microsoft Entra ID). Claude's refresh request carries only the OpenID Connect scopes (openid profile offline_access), and Entra refuses such a request with AADSTS90009 because it names no resource. The connector then works until the access token expires (about an hour), after which every tool call fails ("the token expired, I can't re-authorize from here") until the user reconnects. Set GIZMOSQL_MCP_OAUTH_TOKEN_PROXY=true and the server publishes an authorization-server metadata document at <public origin>/oauth (the provider's own document with issuer and token_endpoint pointing at the server) and proxies the token endpoint at <public origin>/oauth/token: refresh_token grants get the configured API scope and offline_access added, everything else passes through byte for byte, and sign-in still happens at the provider. Each exchange is logged without secrets (OAuth facade: refresh_token (scope added) -> HTTP 200 (refresh_token yes, expires_in 4150s)). Users connected before the proxy was enabled reconnect the connector once so Claude discovers the new token endpoint. See anthropics/claude-ai-mcp#840 for the forensic trail behind this.

Provider notes:

• Microsoft Entra ID does not support dynamic client registration, so the person adding the connector enters the app registration's client ID and secret under Advanced settings. On the registration: redirect URI https://claude.ai/api/mcp/auth_callback (platform Web), Expose an API with the MCP URL itself (https://mcp.example.com/mcp) as an Application ID URI and a scope such as access_as_user, requestedAccessTokenVersion 2, and admin consent for that scope. v2 access tokens carry the client ID as aud, hence GIZMOSQL_MCP_OAUTH_AUDIENCE=<client-id>; set GIZMOSQL_MCP_OAUTH_SCOPES to <Application ID URI>/<scope> openid profile email offline_access so Claude asks for a token for this API rather than for Microsoft Graph and gets a refresh token (Entra only issues one when offline_access is in the request; the Graph delegated permissions openid, profile, email and offline_access must be on the registration), and set GIZMOSQL_MCP_OAUTH_TOKEN_PROXY=true so refreshes are not refused with AADSTS90009 (see Token proxy above). A single-tenant registration plus GIZMOSQL_MCP_OAUTH_AUTHORIZED_EMAILS restricts access to one organisation.
• Okta needs a custom authorization server (tokens from the org server are opaque); Auth0 needs an API with the audience; Keycloak works out of the box and is the easiest local test target; Clerk issues JWT access tokens by default.
• Providers whose access tokens are opaque (Google) are not supported in this mode.

Static bearer token. For a quick shared secret instead of OAuth, set GIZMOSQL_MCP_BEARER_TOKEN; every request must then send Authorization: Bearer <token>, which Claude's connector settings can add as a request header. The two modes are mutually exclusive. With neither set the endpoint is unauthenticated, for local use only.

Container image and Helm chart

Releases publish a multi-arch image, ghcr.io/gizmodata/gizmosql-mcp:<version> (linux/amd64 and linux/arm64), whose entrypoint runs the HTTP transport on port 3000, and a Helm chart, oci://ghcr.io/gizmodata/charts/gizmosql-mcp, that deploys it with a ConfigMap for the GIZMOSQL_* settings, a Secret (or existingSecret) for credentials, and an optional Ingress:

helm upgrade --install gizmosql-mcp oci://ghcr.io/gizmodata/charts/gizmosql-mcp \
  --version <version> --namespace gizmosql-mcp --create-namespace \
  --values values.yaml

See charts/gizmosql-mcp/values.yaml for every option.

Configuration

All settings are environment variables. The extension's settings screen maps onto the same names.

| Variable | Default | Description | | --- | --- | --- | | GIZMOSQL_HOST | required | Hostname or IP of the GizmoSQL server | | GIZMOSQL_CONNECTION_NAME | default | Name of this connection (used with the connection tool argument) | | GIZMOSQL_PORT | 31337 | Flight SQL port | | GIZMOSQL_USERNAME / GIZMOSQL_PASSWORD | | Credentials. For a GizmoSQL JWT (token auth or SSO), the username is token and the password is the JWT | | GIZMOSQL_PLAINTEXT | false | Connect without TLS (development servers only) | | GIZMOSQL_TLS_SKIP_VERIFY | false | Accept self-signed or untrusted certificates | | GIZMOSQL_DEFAULT_CATALOG | | Catalog to USE at the start of every session (optional) | | GIZMOSQL_DEFAULT_SCHEMA | | Schema to USE at the start of every session (optional) | | GIZMOSQL_ALLOW_WRITES | false | Register execute_statement and let run_query run non-read statements | | GIZMOSQL_MAX_ROWS | 500 | Hard cap on rows returned by run_query | | GIZMOSQL_MAX_CELL_CHARS | 200 | Cells longer than this are truncated with … | | GIZMOSQL_QUERY_TIMEOUT_SECONDS | 60 | Per-statement timeout; 0 disables it | | GIZMOSQL_SESSION_REFRESH_SECONDS | auto | Re-apply the USE search path and query timeout before the next statement after this long idle (GizmoSQL may have evicted the session). Unset: derived from the server's gizmosql.session_idle_timeout (GizmoSQL 1.38.5+), else 60; 0 disables | | GIZMOSQL_OAUTH_PORT | 31339 | OAuth HTTP port used by login_sso | | GIZMOSQL_ENABLE_SSO | false | Register the login_sso tool (credentials may then be left empty) | | GIZMOSQL_MCP_BEARER_TOKEN | | HTTP transport: static bearer token (mutually exclusive with OAuth) | | GIZMOSQL_MCP_PUBLIC_URL | | HTTP transport with OAuth: public URL of the /mcp endpoint, the OAuth resource identifier | | GIZMOSQL_MCP_OAUTH_ISSUER | | HTTP transport: OpenID Connect issuer URL; setting it enables OAuth | | GIZMOSQL_MCP_OAUTH_AUDIENCE | public URL | Accepted aud values, comma-separated (Entra ID v2 tokens: the client ID) | | GIZMOSQL_MCP_OAUTH_SCOPES | | Scopes advertised to clients and requested on a 401; include offline_access so a refresh token is issued | | GIZMOSQL_MCP_OAUTH_AUTHORIZED_EMAILS | | Glob allowlist of sign-in emails, e.g. *@example.com | | GIZMOSQL_MCP_OAUTH_TOKEN_PROXY | false | Publish an authorization-server facade at /oauth and proxy the token endpoint so refresh_token grants carry the API scope (required for Entra ID) | | GIZMOSQL_MCP_OAUTH_JWKS_URI | discovered | JWKS endpoint, when discovery from the issuer is not possible | | GIZMOSQL_MCP_OAUTH_USER_CLAIM | email,preferred_username,upn,name,sub | Claims tried in order to name the caller | | GIZMOSQL_MCP_OAUTH_ALLOW_INSECURE | false | Accept http:// issuer and public URLs (local testing only) | | GIZMOSQL_MCP_SESSION_IDLE_SECONDS | 1800 | HTTP transport with OAuth: close a user's session after this long without a request | | GIZMOSQL_MCP_MAX_SESSIONS | 200 | HTTP transport with OAuth: cap on concurrent user sessions | | GIZMOSQL_2_HOST, GIZMOSQL_3_HOST, … | | Additional connections, see below | | GIZMOSQL_CONNECTIONS | | Comma-separated names of further connections, see below |

Every connection needs a username and password (or SSO via login_sso). GizmoSQL's token authentication is a form of basic authentication: username token, password = the JWT, so there is no separate token setting. The default catalog/schema are optional: when set, the server runs USE on each new session so unqualified table names resolve there; if the name does not exist the server still starts and reports the problem (with the catalogs it found) in server_info. In a chat, use_schema or a plain USE catalog.schema switches for the rest of the session. GIZMOSQL_DRIVER_LIB can point at a custom libadbc_driver_gizmosql build if you need one (see the client README).

Multiple connections

You can configure several GizmoSQL servers and switch between them without editing credentials.

• Claude Desktop extension. The settings screen has two extra slots, Connection 2 and Connection 3, each with its own name, host, port, credentials, TLS flags and default catalog/schema. Leave a slot's host blank to disable it. The primary connection's name defaults to default (the Connection name setting changes it).

• Environment variables. The slots map to GIZMOSQL_2_* and GIZMOSQL_3_* (GIZMOSQL_2_HOST, GIZMOSQL_2_NAME, GIZMOSQL_2_USERNAME, GIZMOSQL_2_PASSWORD, GIZMOSQL_2_PORT, GIZMOSQL_2_PLAINTEXT, GIZMOSQL_2_TLS_SKIP_VERIFY, GIZMOSQL_2_DEFAULT_CATALOG, GIZMOSQL_2_DEFAULT_SCHEMA). For any number of servers, list names in GIZMOSQL_CONNECTIONS and define each one with the same variables prefixed by the upper-cased name, for example:

  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=... GIZMOSQL_DEV_EU_PASSWORD=...

  (Non-alphanumeric characters in a name become _ in the variable prefix; GIZMOSQL_<NAME>_NAME overrides the display name.)

In a chat, list_connections shows what is configured, use_connection switches the default for the rest of the session, and every tool accepts a per-call connection argument, so "compare row counts of orders on prod and dev" works in one conversation. The first configured connection is the initial default. Connections are opened lazily; the row cap, timeout and read-only settings apply to all of them, while each server's user role still governs what that connection may do.

Read-only model and security

By default the server refuses anything that is not a read. sql-guard.ts classifies each statement and only lets SELECT, WITH … SELECT, FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE, EXPLAIN, read-style PRAGMA and USE (search path only) through. CTEs that end in DML, COPY, ATTACH, INSTALL, LOAD, SET, CALL, transactions and multi-statement input are all rejected. Setting GIZMOSQL_ALLOW_WRITES=true lifts that restriction and adds execute_statement, which is annotated as destructive so clients ask before running it.

Treat the guard as defense in depth, not as the security boundary. The real boundary is the privileges of the GizmoSQL user the server connects as:

• With username/password authentication every session has the admin role in GizmoSQL.
• With token authentication the JWT's role claim (or the server's --token-default-role) decides the role, and GizmoSQL's built-in readonly role only permits SELECT queries. Mint a token with role: readonly (for example with generate-gizmosql-token) and configure username token with the JWT as the password. GizmoSQL Enterprise adds per-catalog read/write/none permissions in the token as well. See the security guide.

Other guarantees:

• Credentials never appear in tool output, server_info or error messages; every message that reaches the client is redacted.
• The row cap is enforced by the server: reads are executed as SELECT * FROM (<your query>) LIMIT max_rows + 1, and the result is streamed in batches that stop at the cap, never fetched whole and sliced.
• The timeout is enforced by the server too, via SET gizmosql.query_timeout on the session, with a client-side deadline a few seconds later as a backstop that cancels the statement (GizmoSQL 1.38.0 or newer interrupts it server-side). DML/DDL run through execute_statement rely on the server-side timeout alone.
• One connection per process, opened lazily and reconnected once after a connection-level failure, and likewise when GizmoSQL reports that the session behind the bearer token is gone: the server restarted ("Session not associated with this server instance", or the token no longer verifies against a regenerated signing key), or the session was evicted or killed. The reconnect is transparent to the caller and re-applies the search path; only a rejected user credential still surfaces. GizmoSQL's own idle timeout (--session-idle-timeout) evicts a quiet session, and the next request on the same bearer token silently gets a fresh session with the server's defaults, so the USE search path and query timeout would be gone without any error. So the MCP server re-applies both before the next statement after an idle gap (two tiny statements; logged as session settings re-applied after Ns idle). The gap comes from the server itself when it reports gizmosql.session_idle_timeout through gizmosql_settings() (GizmoSQL 1.38.5 or newer): ten percent under the eviction point, or never when eviction is off. Older servers get a 60-second default. GIZMOSQL_SESSION_REFRESH_SECONDS overrides either (0 disables). server_info shows the settings the server reported and the refresh interval in effect. The server has no tools that touch the local filesystem or any network endpoint other than the configured GizmoSQL host (and, for login_sso, its OAuth endpoint).

Troubleshooting

TLS errors (certificate verify failed, x509, unknown authority). GizmoSQL uses TLS by default. For servers with self-signed certificates enable Skip TLS certificate verification (GIZMOSQL_TLS_SKIP_VERIFY=true). For servers started without TLS enable Plaintext (GIZMOSQL_PLAINTEXT=true) instead.

connection refused / Unavailable / timeouts to a 10.x, 172.16.x or 192.168.x address. The extension runs on your machine and connects directly, so you must be on the same network as the server. Connect your VPN first, then start a new chat. Check with nc -vz <host> 31337 from a terminal.

Port-forward setups. If the server is only reachable through SSH or Kubernetes, forward the port locally and point the extension at localhost:

ssh -N -L 31337:gizmosql.internal:31337 bastion.example.com
kubectl port-forward svc/gizmosql 31337:31337

TLS still works through the tunnel; the certificate is validated against the hostname you connect to, so you may need GIZMOSQL_TLS_SKIP_VERIFY=true when the certificate was issued for the internal name.

Authentication failures. server_info shows the user the server is connected as. Username and password must both be set; for a JWT the username is token and the password is the JWT. With SSO, run login_sso first.

Tools do not appear in the chat. Open the + menu in the chat, choose Connectors and enable GizmoSQL. After changing settings, start a new chat.

"No bundled GizmoSQL ADBC driver for this platform". The .mcpb bundles drivers for darwin-arm64, darwin-x64, linux-x64, linux-arm64 and win32-x64. Windows on ARM is not supported yet because the ADBC driver manager has no arm64 build.

Logs. Claude Desktop writes the server's stderr to ~/Library/Logs/Claude/mcp-server-gizmosql.log on macOS and %APPDATA%\Claude\logs\ on Windows. Native driver messages appear there as JSON lines.

npx install did not download the driver. npm 11.19+ asks you to approve install scripts: run npm install-scripts approve @gizmodata/gizmosql-client in the project, or re-run node node_modules/@gizmodata/gizmosql-client/scripts/download-driver.cjs.

Development

npm install
npm run build          # compile to dist/
npm test               # unit tests (node:test)
npm run test:integration   # starts gizmodata/gizmosql:v1.38.1 in Docker (skips without Docker)
                           #   tools.test.ts: every tool over stdio + HTTP with a static token
                           #   sessions.test.ts: hosted HTTP with OAuth (throwaway issuer): per-user
                           #   isolation under concurrency, idle expiry, tool-wide result invariants
                           #   server-versions.test.ts: idle-session refresh against gizmosql v1.38.4
                           #   (no startup settings) and v1.38.5 (reports session_idle_timeout)
npm run lint           # eslint --fix
npm run typecheck
npm run build:mcpb     # build/gizmosql-mcp-<version>.mcpb + .sha256
docker build -t gizmosql-mcp .   # container image for the HTTP transport
helm lint charts/gizmosql-mcp    # Helm chart

Run the server locally against a container:

docker run --name gizmosql --detach --tty --init --publish 31337:31337 \
  --env TLS_ENABLED=1 --env GIZMOSQL_USERNAME=gizmosql --env GIZMOSQL_PASSWORD=gizmosql_password \
  gizmodata/gizmosql:v1.38.1

GIZMOSQL_HOST=localhost GIZMOSQL_USERNAME=gizmosql GIZMOSQL_PASSWORD=gizmosql_password \
GIZMOSQL_TLS_SKIP_VERIFY=true node dist/cli.js

The integration tests can target an existing server instead of Docker with GIZMOSQL_TEST_HOST, GIZMOSQL_TEST_PORT, GIZMOSQL_TEST_USERNAME and GIZMOSQL_TEST_PASSWORD (TLS with an untrusted certificate is assumed).

Releasing

1. Move the [Unreleased] entries in CHANGELOG.md into a new ## [X.Y.Z] - YYYY-MM-DD section and set the same version in package.json, manifest.json, and charts/gizmosql-mcp/Chart.yaml (version and appVersion).
2. Commit, tag vX.Y.Z, and push: git push origin main vX.Y.Z.
3. The release workflow runs the tests, builds the .mcpb, pushes the container image (ghcr.io/gizmodata/gizmosql-mcp) and the Helm chart (ghcr.io/gizmodata/charts), creates a GitHub Release with the bundle, its checksum, the chart and the npm tarball (release notes come from the CHANGELOG section), and publishes @gizmodata/gizmosql-mcp to npm.

See NOTES.md for implementation notes, known limitations and follow-ups.

Privacy Policy

This extension runs entirely on your computer and talks only to the GizmoSQL server you configure (and, when you use login_sso, that server's OAuth endpoint and your identity provider in your browser).

• Data collection. The extension collects nothing. It does not send telemetry, analytics or crash reports to GizmoData or anyone else.
• Usage and storage. The SQL your MCP client sends and the rows the server returns pass through the extension in memory and are handed back to the client; nothing is written to disk. Connection settings are stored by Claude Desktop; credentials marked sensitive are kept in your operating system's keychain. An SSO identity token is held in process memory only and discarded when the extension exits.
• Third-party sharing. Data is shared only with the GizmoSQL server you configured. What your MCP client (for example Claude) does with tool results is governed by that client's own privacy policy.
• Data retention. The extension retains no data between runs. Your GizmoSQL server may log queries according to its own configuration.
• Contact. privacy questions: [email protected]. GizmoData's general privacy policy is at https://gizmodata.com/privacy-policy.

License

Apache License 2.0