Strut Stack Sql

[Strut Stack SQL — Light strut. Extreme load.]

[Latest release] [CI] [License: MIT] [MCP Registry] [PostgreSQL · MySQL · SQLite · DuckDB · ClickHouse · SQL Server]

Light strut. Extreme load.
A token-efficient MCP server that lets AI agents query PostgreSQL, MySQL, SQLite, DuckDB, ClickHouse, and SQL Server — safely, in one small Rust binary.

⭐ If this saves you tokens, star the repo — it is the single biggest thing that helps other people find it.

Install in one command — binary + AI setup included

This is the fastest path. It downloads the release binary (SHA256-verified), then configures every AI tool it finds on your machine — Claude Code, Cursor, VS Code, Claude Desktop, Codex, OpenCode, Windsurf, and Zed — so you do not hand-edit a single JSON file. Existing entries for other servers are kept, and every file it touches is backed up first.

curl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup

With your database URL baked in (recommended):

curl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup --database-url 'postgresql://user:pass@localhost:5432/mydb'

Other useful forms:

# Only specific toolscurl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup --tools cursor,vscode,opencode
# Project-local configs (.cursor/mcp.json, .vscode/mcp.json, .mcp.json, opencode.json, .codex/config.toml)curl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup --project
# Binary already installed? Just do the setup stepcurl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup --skip-install
# Install only, no setupcurl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash

Then restart your AI tool and ask it:

"List the tables in my database, then show me the 5 most recent orders."

You should see the tables listed, then the 5 most recent orders.

If you run the installer without a URL, configs reference ${env:DATABASE_URL} (or forward it, for Codex) — export DATABASE_URL in the environment that launches your editor before starting it. Full installer reference: docs/INSTALL.md.

One-click install

No terminal? These links open your editor with the server pre-filled. Replace the placeholder database URL with your own where prompted.

GitHub does not render cursor:// / vscode: links clickable. If a button above does not open your editor, paste this into your browser's address bar instead:

vscode:mcp/install?%7B%22command%22%3A%22strut-stack-sql%22%2C%22args%22%3A%5B%22--url-env%22%2C%22DATABASE_URL%22%2C%22--full-tools%22%5D%2C%22env%22%3A%7B%22DATABASE_URL%22%3A%22%24%7Binput%3Adatabase_url%7D%22%7D%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22database_url%22%2C%22description%22%3A%22DATABASE_URL%20for%20strut-stack-sql%20%28e.g.%20postgresql%3A%2F%2Fuser%3Apassword%40localhost%3A5432%2Fdbname%29%22%2C%22password%22%3Atrue%7D%5D%7D

Set up by hand (copy-paste)

Prefer the installer above. If you configure by hand, every block below is read-only by default: 13 tools (3 core + 10 introspection), no writes, no DDL. Replace DATABASE_URL with your real URL, or keep --url-env DATABASE_URL and export it. Every block is also machine-checked in docs/CLIENTS.md.

Claude Code

claude mcp add --scope user --transport stdio \  --env DATABASE_URL='postgresql://user:pass@localhost:5432/mydb' \  strut-stack-sql -- strut-stack-sql --url-env DATABASE_URL --full-tools

Or in .mcp.json (project) — Claude Code expands ${VAR} here:

{  "mcpServers": {    "strut-stack-sql": {      "type": "stdio",      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }    }  }}

Check it with claude mcp get strut-stack-sql (or /mcp inside a session).

Cursor

Global ~/.cursor/mcp.json, or project .cursor/mcp.json. Cursor interpolates ${env:NAME}, so this works with an exported DATABASE_URL and no secret in the file:

{  "mcpServers": {    "strut-stack-sql": {      "type": "stdio",      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "${env:DATABASE_URL}" }    }  }}

VS Code

Workspace .vscode/mcp.json (or the user configuration via MCP: Open User Configuration). Note: VS Code uses a top-level servers object, not mcpServers — do not paste a Cursor block here unchanged:

{  "servers": {    "strut-stack-sql": {      "type": "stdio",      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "${env:DATABASE_URL}" }    }  }}

Claude Desktop

claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux):

{  "mcpServers": {    "strut-stack-sql": {      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }    }  }}

Codex

~/.codex/config.toml (or project .codex/config.toml). Codex uses TOML, not JSON:

[mcp_servers.strut-stack-sql]command = "strut-stack-sql"args = ["--url-env", "DATABASE_URL", "--full-tools"]env = { DATABASE_URL = "postgresql://user:pass@localhost:5432/mydb" }startup_timeout_sec = 20

No URL in the file? Use env_vars = ["DATABASE_URL"] instead of env to forward it from Codex's environment.

OpenCode

The CLI is the version-proof path (it writes the right shape for your OpenCode):

opencode mcp add strut-stack-sql --env DATABASE_URL='postgresql://user:pass@localhost:5432/mydb' -- strut-stack-sql --url-env DATABASE_URL --full-tools

Or in opencode.json (global ~/.config/opencode/opencode.json, or project root). command is one array and env vars go in environment, not env:

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "strut-stack-sql": {      "type": "local",      "command": ["strut-stack-sql", "--url-env", "DATABASE_URL", "--full-tools"],      "enabled": true,      "environment": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" },      "timeout": 30000    }  }}

Verify with opencode mcp list. On OpenCode v2, if the server does not appear, nest it under mcp.servers instead of directly under mcp.

Windsurf

~/.config/devin/mcp_config.json (current builds; older builds read ~/.codeium/windsurf/mcp_config.json — use whichever Open MCP config file in Cascade opens):

{  "mcpServers": {    "strut-stack-sql": {      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }    }  }}

Press refresh in Cascade after editing.

Zed

~/.config/zed/settings.json (merged under context_servers, everything else kept):

{  "context_servers": {    "strut-stack-sql": {      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }    }  }}

Any other MCP client

This is the whole contract — stdio, one binary, one env var:

{  "mcpServers": {    "strut-stack-sql": {      "command": "strut-stack-sql",      "args": ["--url-env", "DATABASE_URL", "--full-tools"],      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }    }  }}

Try it

Once your AI tool shows the server as connected, these prompts exercise the whole surface. Start read-only; writes and DDL stay off until you explicitly enable them (see Tools).

"List the tables in my database, with row counts.""Show me the schema of the orders table, including its foreign keys.""Why is this query slow, and which index would fix it?"  (paste any SELECT — analyze_query_performance returns an EXPLAIN tree,   tiered findings, and index advice; the advice is text only, never executed)"Find every table that references customers.id."

What the agent sees: execute_sql returns columnar JSON — column names once, compact meta:

{  "ok": true,  "data": {    "cols": ["id", "email", "name"],    "rows": [[42, "[email protected]", "Ada"]],    "meta": { "n": 1, "truncated": false, "limit_injected": true }  }}

Smoke-test the binary itself (no database needed) — a JSON initialize response means the server speaks MCP:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \  | strut-stack-sql --url 'sqlite::memory:' --full-tools

Connect your database

One URL, one flag. Credentials belong in the environment (or .env discovery in your project), never in a pasted config — prefer --url-env DATABASE_URL.

# Single database, from the environmentDATABASE_URL='postgresql://user:pass@localhost:5432/app' strut-stack-sql --full-tools
# Explicit flag instead of the environmentstrut-stack-sql --url-env DATABASE_URL --full-tools
# Project .env discovery (the server reads .env in your workspace)strut-stack-sql

Multiple databases, per-principal grants, row/byte/timeout ceilings, and redaction live in one TOML file — see strut-stack-sql.example.toml:

# strut-stack-sql.tomldefault_source = "app"
[[sources]]name = "app"url_env = "DATABASE_URL"
[[principals]]id = "alice"
[[grants]]principal = "alice"source = "app"          # or "*"max_tier = "writes"     # read | writes | ddl | adminmax_rows = 200max_bytes = 65536

strut-stack-sql --config ./strut-stack-sql.toml

Full CLI / env / TOML reference: docs/CONFIGURATION.md. Per-engine notes: Postgres · MySQL · SQLite · DuckDB · SQL Server.

Why

Most SQL MCP servers make agents pay three taxes:

1. Token tax — every tool schema and every row-as-object result burns context.
2. Safety tax — raw SQL passthrough means one hallucinated DROP TABLE is a production incident.
3. Footprint tax — a Node/Python runtime just to run SELECT.

Strut Stack SQL does not charge them:

• 3 tools by default — the lite profile. The other 17 are opt-in: 10 introspection tools with --full-tools, and 7 DDL tools only when --full-tools --allow-ddl is set. A fresh install that shows three tools is working as designed.
• Columnar results — {cols, rows, meta} sends column names once, not once per row.
• Every statement passes one AST guard — parsed with sqlparser, classified recursively (including CTE bodies), checked against a tier, LIMIT-clamped, and rejected before a pool connection is checked out.
• One static binary, six engines, behind a stable driver contract.
• Measured, not claimed — idle RSS under 8 MB, tools/list at 2,643 bytes in lite mode (625 tokens o200k_base; 10,853 bytes / 2,549 tokens in full mode), cold start to initialize at 2.52 ms p95 over stdio. Token numbers are v2.0.1 (2026-11-05); runtime numbers are v2.0.0 (2026-11-02). Full numbers and their limits: Benchmarks.

Tools — exactly 20

• search_objects — ranked progressive schema discovery (exact > prefix > substring > comment match).
• execute_sql — single statement, bound parameters, or a governed concurrent batch; columnar / rows / auto output; cursor pagination for large results.
• analyze_query_performance — normalized EXPLAIN tree, tiered findings, index advice (advice text only; never executed).
• get_relationship_graph / suggest_joins / get_schema_context — FK graph, shortest join paths, token-budgeted schema digest.
• DDL aliases require "confirm": true for destructive actions.

Profiles are presets over the same flags — no second authorization system:

strut-stack-sql --profile standard   # read-only, 13 tools (3 core + 10 introspection)

list_tools and invocation use the same authorization function, so a tool hidden from the list is also rejected when called directly. Full schemas and error contract: docs/TOOLS.md.

Safety — read-only by default, fail-closed everywhere else

• AST guard before pool checkout — one statement per string; unknown statement types are denied, not guessed.
• Recursive classification — writes hidden in CTEs (WITH … DELETE … RETURNING … SELECT …), SELECT … INTO, INTO OUTFILE/DUMPFILE, row-locking clauses, and dangerous functions (pg_read_file, LOAD_FILE, pg_sleep, …) are never counted as reads.
• Per-principal grants — read < writes < ddl < admin per principal × source, with optional row/byte/timeout ceilings. The process flags (--allow-writes, --allow-ddl) are a ceiling no grant can exceed.
• Admin gate — GRANT/REVOKE use the separate Admin tier and additionally require --allow-grants.
• Column redaction, not denial — --deny-columns password_hash,totp_secret replaces matching values with "[redacted]": exact, case-insensitive column-name match, column names stay visible. An alias (SELECT password AS p) evades it, so treat it as a seat-belt, not an access-control boundary — use a read-only database user and views that never select the secret. DuckDB's guard additionally blocks read_csv, read_text, ATTACH, INSTALL, and LOAD so an agent cannot read files outside the allowlist.
• Dry runs and explicit consent — DDL accepts dry_run: true (parse, classify, and report without executing), destructive aliases require confirm: true, and the admin profile adds single-use approvals (approval_id / MCP elicitation) on top.
• Per-database allowlist (opt-in) — --allow-databases app,analytics denies cross-database table qualifiers, hides other databases from list_schemas, and rejects schema: "*"; unqualified names still resolve on the connected database, so pair it with a database-scoped credential (limits).
• HTTP auth — STRUT_STACK_SQL_HTTP_TOKENS entries are name:secret:mode[:source…]; secrets may be stored as sha256:<64 hex> and are compared in constant time. OAuth 2.1 resource-server mode validates RS256 JWTs against the issuer's JWKS and fails closed if discovery fails. A non-loopback HTTP bind with no auth fails startup unless --allow-unauthenticated-http is passed explicitly.

Remote HTTP mode:

STRUT_STACK_SQL_HTTP_TOKENS="alice:s3cr3t:readonly" \  strut-stack-sql --http 0.0.0.0:8080

Full model: docs/SECURITY.md. Safe probes: /livez never touches a database; /readyz uses cached pool status and never returns raw database errors.

Security boundary and limitations

Defense in depth, not a sandbox. The controls in the Safety section above are real, but none of them replaces least-privilege database accounts, network restrictions, and review of SQL privileges.

• The guard parses SQL; it does not understand intent. Statements are parsed with sqlparser into an AST and classified recursively (including CTE bodies); anything the parser cannot represent is rejected, not guessed. That is a policy check on the statement's shape — not a proof that the query is safe to run against your data.
• Database privileges remain decisive. Run the server with a dedicated, least-privilege database account — never an administrative one — and isolate demonstration environments. A read-only database user and views that never select the secret are the real boundary; --deny-columns is a seat-belt, not a wall (an alias evades the name match).
• Treat credentials as secrets. Never commit .env files, real token hashes, raw tokens, or logs containing sensitive SQL.
• Transport needs deployment security. Bind locally for development. The HTTP transport must not be exposed publicly without a properly secured TLS / reverse-proxy and network policy — a non-loopback bind without auth fails startup unless --allow-unauthenticated-http is passed explicitly.
• There is no persistent audit log yet. Tool calls and SQL text can appear in logs — control log access, rotation, retention, and redaction according to your environment. A JSONL audit log with agent identity is on the roadmap, not in this release.
• This is not a security certification. Review and test it before any production deployment. Data returned through tools must be treated as untrusted content, not as instructions to the agent.

What exists today, what is still on the roadmap, and how to report a vulnerability (privately): SECURITY.md. The full threat model lives in docs/SECURITY.md.

More ways to install

The installer above is recommended. Everything below installs the same binary; full matrix and release asset names: docs/INSTALL.md.

# Homebrew (macOS)brew install rzlco666/tap/strut-stack-sql
# Windowsscoop install rzlco666/strut-stack-sql# orwinget install rzlco666.strut-stack-sql
# Docker (no install at all)docker run --rm -i -e DATABASE_URL='postgresql://user:pass@host:5432/db' \  ghcr.io/rzlco666/strut-stack-sql:latest
# From source (crates.io publication is off)cargo install --path . --bins

MCPB bundles for every platform are attached to each GitHub Release and described by server.json for the MCP Registry.

Open source

The whole stack is MIT licensed: one static Rust binary for six engines (PostgreSQL, MySQL, SQLite, DuckDB, ClickHouse, SQL Server), with the guard, formatter, tools, server, and drivers as separate crates. Choose a surface with --profile lite|standard|full|admin instead of maintaining four builds — profiles are presets over the same flags and grants, not a second authorization system (docs/PROFILES.md).

• Security model and threat model: docs/SECURITY.md.
• Install channels: one-line installer, Homebrew, Scoop, winget, Docker, cargo install --path ., and per-platform MCPB bundles (docs/INSTALL.md).
• Contributions: docs/CONTRIBUTING.md.

Architecture

flowchart LR  Agent[AI agent] -->|stdio / Streamable HTTP| Server[strut-sql-server]  Server --> Tools[strut-sql-tools]  Tools --> Guard[strut-sql-guard]  Guard -->|allow| DriverAPI[strut-sql-driver-api]  Guard -->|deny| NoDB[Reject before pool checkout]  DriverAPI --> PG[strut-sql-driver-postgres]  DriverAPI --> MY[strut-sql-driver-mysql]  DriverAPI --> SQ[strut-sql-driver-sqlite]  DriverAPI --> DK[strut-sql-driver-duckdb]  DriverAPI --> CH[strut-sql-driver-clickhouse]  DriverAPI --> MS[strut-sql-driver-sqlserver]  PG --> DB[(PostgreSQL)]  MY --> DB2[(MySQL)]  SQ --> DB3[(SQLite)]  DK --> DB4[(DuckDB file / memory)]  CH --> DB5[(ClickHouse HTTP)]  MS --> DB6[(SQL Server)]  Tools --> Format[strut-sql-format]  Server --> Core[strut-sql-core]

Thirteen crates plus a thin binary. The core, guard, format, tools, and server crates never import a database library; only a driver crate does. The driver boundary is one trait (EngineDriver in crates/strut-sql-driver-api): drivers own connections, execution, and catalogs, while dialect selection, capability checks, authorization, and tool SQL generation stay shared. Full crate map: docs/ARCHITECTURE.md.

Benchmarks (measured)

Raw artifact: scripts/benchmark/results/2.0.0.json — 2026-11-02, WSL2 Ubuntu 24.04, Intel i5-13420H (6 vCPU), 5.79 GB RAM, SQLite temp database, n=120 iterations after 20 warmups, 20 cold-start runs. Reproduce with ./scripts/benchmark/run-bench.sh. The table below is the v2.0.0 runtime benchmark — for the v2.0.1 token numbers, see Token benchmark below.

Two measurement classes are kept apart instead of blended:

• In-process — engine work on a local SQLite file. tools/list is 3,039 bytes (v2.0.0) for the core surface, and a 100 × 8 result is 7,526 bytes of columnar text before truncation (column names once, not once per row). These numbers describe payload shape, not network cost.
• Roundtrip over stdio/HTTP — process spawn → initialize, plus one request/response per execute_sql. The 0.80 ms stdio p50 includes local SQLite execution and JSON-RPC framing; the harness cannot split tool overhead from database time on an in-process file.

The two HTTP misses are real and are not rounded away: cold start includes listener readiness and the session handshake, and each HTTP execute_sql is a fresh request, so transport framing dominates. PostgreSQL and MySQL were not measured (no live server on the reference machine) and are recorded as not_run, together with the competitor comparison. Methodology and limits: docs/BENCHMARKS.md.

Token benchmark (v2.0.1)

Measured 2026-11-05 (run 1) and independently re-run 2026-11-06 (run 2, byte-identical payloads) against the v2.0.1 release binary (strut-stack-sql 2.0.1, commit 805d18f, MCP protocol 2025-06-18, tiktoken 0.14.0). Tokens count only what the model sees — per-tool name + description + inputSchema (method: octomind.run, 2026-10-02). These are schema tokens, not session tokens and not a Claude bill. Full method, per-tool tables, and reproduction steps: docs/TOKEN-BENCHMARK.md.

Raw tools/list payloads: lite 2,643 B, standard 5,679 B, full 10,853 B. The old headline figure of 3,039 bytes was the v2.0.0 payload; it does not apply to v2.0.1. Token budgets (lite ≤ 750, full ≤ 3,000 o200k_base) are adopted design budgets; the CI job enforcing them is follow-up work, not yet a gate.

Protocol and clients

• Pinned MCP specification: 2025-06-18. Version negotiation, tools/list, tools/call, error shapes, Streamable HTTP sessions, auth metadata, and DNS-rebinding Origin checks are exercised by a runnable gate. Older requested versions are answered with 2025-06-18; JSON-RPC batches are rejected.
• Eight-client setup, six-client checked matrix: the installer and the copy-paste blocks above cover Claude Code, Cursor, VS Code, Claude Desktop, Codex, OpenCode, Windsurf, and Zed. The six-client matrix in docs/CLIENTS.md (Cursor, Claude Code, VS Code, Codex, Windsurf, OpenCode) has every config block parsed and the minimal stdio command smoke-run in CI.
• Historical 2.0.0 conformance results: docs/CONFORMANCE.md.

Troubleshooting

Documentation

Contributing

Issues and PRs welcome — start with docs/CONTRIBUTING.md. Include a minimal SQL repro for guard issues (never production credentials).

License

MIT

Built for agents that should ask the database, not guess it.
⭐ Star it if it earns its place in your stack — and tell one person who still pastes SQL into chat.