mssql-mcp-server

mssql-mcp-server

An MCP server that lets an LLM (Claude, etc.) discover schemas, run queries, and build live dashboards across one or more Microsoft SQL Server instances.

Design goals: predictable JSON, multi-server first, easy to install, no parser sitting between Claude and the database. Read-only enforcement is delegated to the SQL login's permissions — keep your read-only logins read-only.

Install

As a Claude Code plugin (recommended)

/plugin marketplace add bherbruck/mssql-mcp-server
/plugin install mssql-mcp-server

Then add your first connection from inside Claude Code:

/mssql:add-server

Other connector commands:

Command	What it does
/mssql:add-server [name]	Wizard: host, db, auth, password. Writes to ~/.config/mssql-mcp-server/config.yaml.
/mssql:list-servers	Show every configured connection.
/mssql:remove-server [name]	Delete a connection.
/mssql:test-connection [name]	Round-trip check via get_server_info.

Config is hot-reloaded — adding/removing servers is picked up immediately. The only thing that needs a restart is setting a new password_env env var, since env vars are inherited at process start.

Claude Desktop — one-click install (.mcpb)

Grab the latest mssql-mcp-server.mcpb from Releases and double-click. Claude Desktop opens a form to fill in host, database, login, and password. Install. Done. No JSON editing, no npx cold start, no global node install — Desktop ships its own runtime.

Standalone (Claude Desktop manual, other MCP clients)

Four ways to configure, listed simplest first. Pick whichever fits.

1. Plain env vars — single server, no nested JSON, no extra files. Easiest for one-off setups.

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "github:bherbruck/mssql-mcp-server"],
      "env": {
        "MSSQL_HOST": "sql.example.com",
        "MSSQL_DATABASE": "Sales",
        "MSSQL_USER": "reader",
        "MSSQL_PASSWORD": "hunter2"
      }
    }
  }
}

Recognized vars: MSSQL_HOST, MSSQL_DATABASE, MSSQL_PORT, MSSQL_USER (or MSSQL_USERNAME), MSSQL_PASSWORD (or MSSQL_PASSWORD_ENV for indirection), MSSQL_AUTH (sql | windows), MSSQL_NAME (alias, default default), MSSQL_READ_ONLY, MSSQL_ENCRYPT, MSSQL_TRUST_SERVER_CERTIFICATE.

2. Config file — multi-server or when you want hot-reload on edits. Default location is ~/.config/mssql-mcp-server/config.yaml; override with --config or $MSSQL_MCP_CONFIG. YAML or JSON (JSON is valid YAML 1.2).

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "github:bherbruck/mssql-mcp-server", "--config", "/abs/path/to/db.json"]
    }
  }
}

3. Full JSON inline via env var — multi-server without a separate file. No hot reload.

{
  "env": {
    "MSSQL_MCP_CONFIG_JSON": "{\"servers\":{\"prod\":{\"host\":\"...\",\"database\":\"...\",\"auth\":{\"kind\":\"sql\",\"username\":\"...\",\"password\":\"...\"}}}}"
  }
}

4. Full JSON inline via CLI flag — same content, travels in args. Equivalent to option 3.

{
  "args": ["-y", "github:bherbruck/mssql-mcp-server", "--config-json", "{...}"]
}

Precedence when multiple are set: --config-json → MSSQL_MCP_CONFIG_JSON → MSSQL_HOST env vars → --config file → $MSSQL_MCP_CONFIG → default path.

From source

git clone https://github.com/bherbruck/mssql-mcp-server
cd mssql-mcp-server
npm install
npm run build
npm test
npm start -- --config ./config.yaml

Configuration

See config.example.yaml. The shape:

default_server: prod         # optional; if set, tools can omit `server`

defaults:
  max_rows: 1000             # truncation cap for query() unless overridden
  timeout_ms: 30000
  read_only: true            # informational; real enforcement is the SQL login

servers:
  prod:
    host: prod-sql.company.com
    port: 1433
    database: Sales
    auth:
      kind: sql              # sql | windows
      username: claude_reader
      password_env: PROD_SQL_PASSWORD
    encrypt: true
    trust_server_certificate: false

Two auth modes:

Mode	When to use	Driver
sql	Anywhere. Cross-platform. SQL Server with a SQL login.	tedious (bundled)
windows	Windows host, integrated auth.	msnodesqlv8 (optional peer install)

For Windows authentication, install the optional driver:

npm install msnodesqlv8

Then in config: auth: { kind: windows }. The host must be Windows; msnodesqlv8 does not work on Mac/Linux.

Tools