Skip to content

install.md

Latest commit

 

History

History
93 lines (68 loc) · 5.1 KB

install.md

File metadata and controls

93 lines (68 loc) · 5.1 KB

Installing the StackQL MCP server

There are three ways to get the StackQL MCP server into a client (Claude Desktop, Cursor, VS Code, Cline, etc.), in order of how much trust and how little effort each takes.

1. From a marketplace / directory (recommended once listings are live)

  • Claude Desktop -> Browse extensions - search for "StackQL". Click install. (Available once the Anthropic Desktop Extensions submission is accepted; see anthropic-submission.md.)
  • Cursor / VS Code / Cline marketplaces - search for "StackQL"; listings auto-ingest from the Official MCP Registry.

These flows are signed by the directory's own review process and verified against the SHA-256 we publish.

2. Direct .mcpb install (Claude Desktop, manual)

Download the .mcpb for your platform from the latest stackql release:

  • Linux x86_64: https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-x64.mcpb
  • Linux arm64: https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-linux-arm64.mcpb
  • Windows x86_64: https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-windows-x64.mcpb
  • macOS (universal): https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-darwin-universal.mcpb

Each .mcpb has a matching .sha256 next to it on the release page. To verify before installing:

# Linux / macOS
sha256sum -c stackql-mcp-linux-x64.mcpb.sha256
# Windows (PowerShell)
(Get-FileHash stackql-mcp-windows-x64.mcpb -Algorithm SHA256).Hash -eq (Get-Content stackql-mcp-windows-x64.mcpb.sha256).Split()[0]

Then drag the .mcpb onto Claude Desktop (or open it from the Extensions panel). Claude Desktop will currently show the bundle as unsigned - that is expected (see Trust model below); the embedded binary inside is fully Apple-notarised / Authenticode-signed depending on platform.

3. Manual claude_desktop_config.json (any client that supports stdio MCP)

If you'd rather wire the existing stackql binary on your machine directly (no bundle, no Claude Desktop install flow), add an entry to your client's MCP config. For Claude Desktop the file is:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Add the stackql server entry. Adjust command to the absolute path of your stackql binary if it is not on PATH, and replace /Users/you with your actual home directory (no variable substitution happens in this file):

{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--approot", "/Users/you/.stackql",
        "--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
      ]
    }
  }
}

All three extra arguments matter:

  • --mcp.server.type=stdio is required - without it the server starts but does not produce JSON-RPC on stdout.
  • --approot must point somewhere writable. Claude Desktop launches MCP servers with cwd / (read-only on macOS), and stackql's default approot is <cwd>/.stackql, so without this flag provider downloads fail.
  • The --mcp.config audit setting is required for the same reason: the audit sink defaults to a file in the cwd and the server exits if it cannot open it (failure_mode defaults to strict). Alternatively set {"server": {"audit": {"file": {"path": "/Users/you/.stackql/stackql-mcp-audit.log"}}}} to keep auditing with an explicit writable path.

With cloud provider credentials

The server picks up provider credentials through stackql's normal --auth flag. For example, to query AWS with an environment-backed access key and GitHub in no-auth mode:

{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--auth={\"aws\":{\"type\":\"aws_signing_v4\",\"credentialsenvvar\":\"AWS_SECRET_ACCESS_KEY\",\"keyID\":\"AWS_ACCESS_KEY_ID\"},\"github\":{\"type\":\"null_auth\"}}"
      ]
    }
  }
}

See https://stackql.io/docs for the full provider auth catalogue.

Trust model

What you get with a fresh StackQL .mcpb install:

  1. The bundled binary is Apple-notarised (macOS) or Authenticode-signed (Windows). Gatekeeper and SmartScreen validate it at run time. Linux binaries are unsigned by convention.
  2. The .mcpb envelope is not currently signed - the EV code-signing cert that signs the upstream stackql.exe is HSM-resident and incompatible with the mcpb sign CLI today. The Claude Desktop install dialog will note "unsigned" for the bundle envelope. The binary inside it is still fully signed.
  3. The .mcpb SHA-256 is published next to the release asset and pinned in the Official MCP Registry entry. Marketplaces and the mcp-publisher flow verify it before install.

If you want envelope-signed bundles before installing, build from source with make signed VERSION=X.Y.Z and a self-signed cert, or wait for the upstream @anthropic-ai/mcpb CLI to add HSM support so the production EV cert can sign envelopes directly.