Mssql MCP

mssql-mcp

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 and docs/security-posture.md for the full security posture (OpenSSF Scorecard, SBOM, branch protection, supply-chain attestation).

Contents

• Quick start
• Installation
  • Platform matrix
  • How the binary is delivered
  • Docker
  • Windows note
• Supported clients
• Validate it works
• Why this exists
• Access modes
• Tools
• Examples
• Authentication
• Configuration
  • CLI reference
• Troubleshooting
• Security
• Development
• Trademarks & licensing
• Contributing
• Stability
• 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.

2. Add the server to your MCP client.

For example, a Claude Desktop configuration uses ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). This is a configuration example, not a recorded manual verification; confirm the location/schema for your client version:

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

Replace every <...> placeholder with your real SQL Server details. For other clients, see 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 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

Windows retains the existing framework-dependent distribution and requires .NET 10. All platforms now use managed SNI; native SNI assets are explicitly excluded even from framework-dependent and NuGet tool packages. Windows selects SqlClient's managed networking switch. See Architecture & decisions.

The Entra authentication extension was removed from unreleased builds because its native broker dependency prohibits redistribution. SQL password and Windows Integrated Authentication remain supported; Authentication=Active Directory ... modes are no longer supported. See Authentication.

How the binary is delivered

The npm package uses per-platform optionalDependencies (@codegiveness/mssql-mcp-<rid>) — 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/<version>/<rid>/. 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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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 uses MCP over stdio and is designed to work with compatible harnesses (MCP client applications). The user reports successful production use with Oh My Pi and OpenCode. This is user-reported evidence, not a dated 30-day usage log or a recorded verification of specific OS versions, client versions, configuration paths, or logs.

Evidence limits: the automated MCP stdio smoke check exercises initialization, tool discovery, and a real SQL Server tool call. It does not verify each GUI harness. In particular, the six historical examples—Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline/Roo Code, and Continue—are configuration examples, not claimed manually verified integrations. The other snippets below are examples as well. Confirm your installed client's current configuration schema and file location, then replace the <...> placeholders with your SQL Server details. Manual six-harness verification is no longer a release gate; see ADR-0036.

The placeholder connection string used throughout is:

Server=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-password>;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Claude Code

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