Mssql Mcp

mssql-mcp

[](https://github.com/codegiveness/mssql-mcp/actions/workflows/ci.yml) [](https://www.nuget.org/packages/codegiveness.mssql-mcp) [](https://www.npmjs.com/package/@codegiveness/mssql-mcp) [](https://dotnet.microsoft.com/) [](./LICENSE) [](https://scorecard.dev/viewer/?uri=github.com/codegiveness/mssql-mcp) [](https://bestpractices.dev/) [](./docs/security-posture.md#supply-chain-attestation) [](./SECURITY.md)

An MCP server that lets AI agents safely query Microsoft SQL Server — read-only by default, with AST validation, transaction rollback, and timeouts.

> Security & trust. The server runs in Restricted mode (read-only) by default. Provide a least-privilege connection string — a SQL login that can only SELECT from the databases you want the agent to see. Secrets are passed via the MSSQL_CONNECTION_STRING environment variable, never command-line arguments. See [SECURITY.md](./SECURITY.md) and [docs/security-posture.md](./docs/security-posture.md) for the full security posture (OpenSSF Scorecard, SBOM, branch protection, supply-chain attestation).

Contents

• [Quick start](#quick-start)
• [Installation](#installation)
• [Platform matrix](#platform-matrix)
• [How the binary is delivered](#how-the-binary-is-delivered)
• [Docker](#docker)
• [Windows note](#windows-note)
• [Supported clients](#supported-clients)
• [Validate it works](#validate-it-works)
• [Why this exists](#why-this-exists)
• [Access modes](#access-modes)
• [Tools](#tools)
• [Examples](#examples)
• [Authentication](#authentication)
• [Configuration](#configuration)
• [CLI reference](#cli-reference)
• [Troubleshooting](#troubleshooting)
• [Security](#security)
• [Development](#development)
• [Trademarks & licensing](#trademarks--licensing)
• [Contributing](#contributing)
• [Stability](#stability)
• [Architecture & decisions](#architecture--decisions)

Quick start

1. Verify the binary runs on your machine.

macOS / Linux:

npx -y @codegiveness/mssql-mcp --version

Windows (requires .NET 10 runtime):

dotnet tool install -g codegiveness.mssql-mcp
mssql-mcp --version

You should see the mssql-mcp version printed. If it prints, the install is good. If it fails, see [Troubleshooting](#troubleshooting).

2. Add the server to your MCP client.

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Replace every `` placeholder with your real SQL Server details. For other clients, see [Supported clients](#supported-clients) below.

3. Validate the connection.

npx -y @codegiveness/mssql-mcp --validate

Prints [startup] Connection validated successfully. — you're done. See [Validate it works](#validate-it-works) for what to do if it fails.

Installation

The Quick start above covers the common path. This section covers platform details, Docker, and Windows-specific notes.

Platform matrix

| RID | Self-contained | Archive | Notes | |---|---|---|---| | linux-x64 | yes | .tar.gz | npx -y @codegiveness/mssql-mcp just works | | linux-arm64 | yes | .tar.gz | npx -y @codegiveness/mssql-mcp just works | | osx-x64 | yes | .tar.gz | Intel Macs | | osx-arm64 | yes | .tar.gz | Apple Silicon | | win-x64 | no (framework-dependent) | .zip | Requires .NET 10 runtime; dotnet tool install is the recommended path |

Windows is framework-dependent because the self-contained build would bundle Microsoft.Data.SqlClient.SNI under the Microsoft "Distributable Code" license, whose anti-copyleft clause conservatively blocks redistribution under our MIT license. Linux and macOS use the managed SNI implementation (MIT-clean). This is the distribution rationale — see [Architecture & decisions](#architecture--decisions) for the full ADR.

How the binary is delivered

The npm package uses per-platform optionalDependencies (@codegiveness/mssql-mcp-) — npm's dependency resolution installs the matching package automatically, no postinstall script involved. This works even with --ignore-scripts.

The shim (npm/bin/mssql-mcp.js) runs on every invocation:

1. Resolves the per-platform optional dependency via require.resolve and execs the binary directly (happy path).
2. If the optional dependency is absent (--no-optional, corporate mirrors), checks the cache at ~/.mssql-mcp/bin///. If cached, execs it.
3. If not cached, downloads the flat archive from the matching GitHub Release, verifies the .sha256 sidecar, extracts, chmod 755 (Unix), caches, and execs. Set MSSQL_MCP_NO_DOWNLOAD=1 to skip the download attempt.

Every failure mode prints the RID, the GitHub Releases URL for manual download, and the dotnet tool install -g codegiveness.mssql-mcp fallback.

Docker

A Dockerfile is included for containerized deployments (Linux x64, self-contained):

docker build -t mssql-mcp .
docker run --rm -e MSSQL_CONNECTION_STRING="Server=...;Database=...;User Id=...;Password=...;Encrypt=True;TrustServerCertificate=True;" mssql-mcp --validate

To point your MCP client at the Docker image, use docker as the command:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "MSSQL_CONNECTION_STRING", "mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

The -i flag keeps stdin open for the MCP stdio transport. The image must be built first: docker build -t mssql-mcp .

Windows note

npx -y @codegiveness/mssql-mcp on Windows delivers a framework-dependent build via optionalDependencies. The build requires the .NET 10 runtime to be installed. If the runtime is missing, the shim prints a clear error with the download URL and the dotnet tool install fallback. If you don't want to install the runtime, install the .NET tool instead:

dotnet tool install -g codegiveness.mssql-mcp

Supported clients

mssql-mcp works with any MCP-compatible client (we call them harnesses). Pick yours below. Every snippet is copy-paste-ready — just replace the `` placeholders with your SQL Server details.

The placeholder connection string used throughout is:

Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;

> Windows / dotnet tool users: If you installed via dotnet tool install -g codegiveness.mssql-mcp, replace "command": "npx" and "args": ["-y", "@codegiveness/mssql-mcp"] with "command": "mssql-mcp" (no args) in any snippet below.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Claude Code

Edit ~/.claude.json (user-level) or .mcp.json in your project root:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows):

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

VS Code / GitHub Copilot

Edit .vscode/mcp.json in your workspace (or ~/.vscode/mcp.json for global):

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Cline / Roo Code

Edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (VS Code extension path):

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Continue

Edit ~/.continue/config.json:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

opencode

Edit ~/.config/opencode/opencode.json (user-level) or opencode.json in your project root. opencode uses a "mcp" key (not "mcpServers"), "command" as an array, and "environment" (not "env"):

{
  "mcp": {
    "mssql-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@codegiveness/mssql-mcp"],
      "enabled": true,
      "environment": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.mssql-mcp]
command = "npx"
args = ["-y", "@codegiveness/mssql-mcp"]

[mcp_servers.mssql-mcp.env]
MSSQL_CONNECTION_STRING = "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"

Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Antigravity IDE

Edit ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  mssql-mcp:
    command: npx
    args:
      - "-y"
      - "@codegiveness/mssql-mcp"
    env:
      MSSQL_CONNECTION_STRING: "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"

Kiro

Edit ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "mssql-mcp": {
      "command": "npx",
      "args": ["-y", "@codegiveness/mssql-mcp"],
      "env": {
        "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Zed

Edit ~/.config/zed/settings.json (macOS/Linux) or %APPDATA%\Zed\settings.json (Windows). The mssql-mcp server goes under assistant.mcp_servers:

{
  "assistant": {
    "mcp_servers": {
      "mssql-mcp": {
        "command": "npx",
        "args": ["-y", "@codegiveness/mssql-mcp"],
        "env": {
          "MSSQL_CONNECTION_STRING": "Server=;Database=;User Id=;Password=;Encrypt=True;TrustServerCertificate=True;"
        }
      }
    }
  }
}

Validate it works

After adding the config, run --validate from your terminal. This proves the server can start and connect to SQL Server — without needing the harness at all:

npx -y @codegiveness/mssql-mcp --validate

What success looks like:

[startup] Connection validated successfully.

Exit code 0. The binary runs, the connection string is valid, and SQL Server accepted it.

What failure looks like:

[startup] Connection validation failed [tag]: 

Exit code 1. The tag tells you the category:

| Tag | Meaning | Next step | |---|---|---| | timeout | Server didn't respond in time | Check the hostname/port, firewall rules, and that SQL Server accepts TCP connections. | | connection | Network-level failure (refused, DNS, etc.) | Verify the Server= value, that SQL Server is running, and that port 1433 (or your custom port) is reachable. | | auth | Login failed | Double-check User Id and Password. If using Entra ID, verify the Authentication= setting. | | certificate | TLS/SSL handshake failed | See [Troubleshooting: connection / login failed](#connection-failed--login-failed) below — usually TrustServerCertificate=True is needed for self-signed certs. |

If --validate passes but your harness can't see the server, the problem is in the harness config — see [Troubleshooting: agent can't see the server](#agent-cant-see-the-server).

Why this exists

mssql-mcp gives AI agents a small, well-typed tool surface backed by AST validation, read-only transactions, timeouts, and a byte-size transport safety net — so an agent can explore schema, run SELECTs, and analyze query plans without a human in the loop, by default.

| Feature | mssql-mcp | |---|---| | Guardrails | AST validation + read-only transactions | | Destructive SQL | Blocked by default (rollback) | | Tool surface | 9 typed tools | | Transport safety | Byte-size limit on stdio | | Language | C#/.NET 10 | | Target DB | SQL Server |

Access modes

mssql-mcp ships in two modes, selected at startup via --access-mode or MSSQL_ACCESS_MODE:

• Restricted (default) — read-only. The Guard enforces an AST allowlist, wraps every query in BEGIN TRAN ... ROLLBACK, applies a per-query command timeout, and truncates oversized results with a notice. All tools carry readOnlyHint=true. This is the mode to use with AI agents.
• Unrestricted (opt-in) — full DML/DDL via execute_sql. The Guard is bypassed for execute_sql, destructive operations carry destructiveHint=true, and the default query timeout is unlimited. Use this only when the human operator has explicitly authorized schema changes or writes. explain_query is still Guarded in both modes (it never executes the query).

mssql-mcp --access-mode unrestricted
# or
MSSQL_ACCESS_MODE=unrestricted mssql-mcp

Tools

Nine tools, all readOnlyHint=true in Restricted mode. execute_sql gains destructiveHint=true in Unrestricted mode.

| Tool | Description | |---|---| | list_databases | List all databases with an is_current flag (system DBs excluded). | | list_schemas | List schemas in the current or specified database. | | list_objects | List tables/views/procedures/functions with schema, type, and limit filters (default 1000). | | get_object_details | Return columns, parameters, indexes, and triggers for a specific object. | | execute_sql | Execute a T-SQL batch. SELECT in Restricted; DML/DDL in Unrestricted. | | explain_query | Show the execution plan summary (or raw XML) without executing the query. | | analyze_indexes | Missing-index analysis from sys.dm_db_missing_index_* DMVs (workload-wide or per-query). | | get_top_queries | Top queries by CPU/duration/r

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: codegiveness
• Source: codegiveness/mssql-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.