strut-stack-sql MCP server

Latest release: v2.0.2 — release notes (2026-11-06). Patch release: the --profile flag is honoured again, .mcpb manifest descriptions corrected, the measured token benchmark published (lite 625 / full 2,549 tokens), and a CI job now enforces the token budgets (lite ≤ 750 / full ≤ 3,000) on every run. No tool-schema changes from v2.0.1. Listed on the official MCP Registry as io.github.rzlco666/strut-stack-sql.

---

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 tools
curl -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 step
curl -fsSL https://raw.githubusercontent.com/rzlco666/strut-stack-sql/main/install.sh | bash -s -- --setup --skip-install

# Install only, no setup
curl -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.

Client	One-click
Cursor	Add to Cursor
VS Code	Install in VS Code
Claude Desktop	Download the .mcpb bundle for your platform from Releases and open it — it asks for DATABASE_URL and installs itself.

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, "ada@example.com", "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.

Engine	URL format	Notes
MySQL / MariaDB	mysql://user:pass@host:3306/dbname	mariadb engine hint maps here
PostgreSQL	postgresql://user:pass@host:5432/dbname
SQLite	sqlite:///absolute/path/app.db, sqlite::memory:	Constrain files with --sqlite-allowlist DIR[,DIR…]
DuckDB	duckdb:///absolute/path/analytics.duckdb, duckdb::memory:	Embedded engine; constrain files with --duckdb-allowlist DIR[,DIR…]; :memory: is read-only via the guard
SQL Server	sqlserver://user:pass@host:1433/dbname (mssql:// alias)	TLS + certificate validation default on
ClickHouse	clickhouse://host:8123/db, clickhouses://host:8443/db	HTTP interface; s = TLS

# Single database, from the environment
DATABASE_URL='postgresql://user:pass@localhost:5432/app' strut-stack-sql --full-tools

# Explicit flag instead of the environment
strut-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.toml
default_source = "app"

[[sources]]
name = "app"
url_env = "DATABASE_URL"

[[principals]]
id = "alice"

[[grants]]
principal = "alice"
source = "app"          # or "*"
max_tier = "writes"     # read | writes | ddl | admin
max_rows = 200
max_bytes = 65536

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

Full CLI / env / TOML reference: docs/CONFIGURATION.md. Per-engine notes: MySQL · Postgres · 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 were measured on the v2.0.1 binary (2026-11-05) and still apply to v2.0.2 — the patch changes no tool schemas — and the CI token-budget job now enforces the budgets on every run; runtime numbers are v2.0.0 (2026-11-02). Full numbers and their limits: Benchmarks.

Tools — exactly 20

Surface	Flag	Tools
Core (always)	—	search_objects, execute_sql, analyze_query_performance
Introspection (10)	--full-tools	list_sources, list_schemas, list_tables, describe_table, list_indexes, list_foreign_keys, schema_overview, get_relationship_graph, suggest_joins, get_schema_context
DDL (7)	--full-tools --allow-ddl	schema_mutate, create_table, drop_table, add_column, alter_column, drop_column, truncate_table

• 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:

Profile	Write mode	--full-tools	Approvals
lite	read-only	no	no
standard	read-only	yes	no
full	writes	yes	no
admin	ddl	yes	required

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 / Scoop / winget: manifests live in packaging/ but are not
# published yet (no tap/bucket upstream) — use the installer, Docker, or
# MCPB above until they are.

# 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 --url-env DATABASE_URL

# From source (crates.io publication is off)
cargo install --path . --bins

The image defaults to HTTP mode on port 8000; without --http the image runs in stdio mode.

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 (MySQL, PostgreSQL, SQLite, DuckDB, SQL Server, ClickHouse), 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.