Mssql MCP README

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:

{
  "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;"
      }
    }
  }
}

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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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=<your-server>;Database=<your-database>;User Id=<your-username>;Password=<your-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]: <obfuscated error>

Exit code 1. The tag tells you the category:

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.

Why this exists

mssql-mcp gives AI agents a small, well-typed tool surface backed by AST validation, rollback wrappers, timeouts, and a byte-size transport safety net. Use a least-privilege SQL login: application checks are not a database authorization boundary.

Access modes

mssql-mcp ships in two modes, selected at startup via --access-mode or MSSQL_ACCESS_MODE. Only the case-insensitive names restricted and unrestricted are accepted; numeric and combined enum values are rejected:

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

For full input schemas and return shapes, see ADR-0016.

Examples

list_databases

Agent calls:

{"method": "tools/call", "params": {"name": "list_databases"}}

Server returns:

[
  {"name": "mydb", "is_current": true},
  {"name": "reporting", "is_current": false}
]

execute_sql

Agent calls:

{"method": "tools/call", "params": {"name": "execute_sql", "arguments": {"sql": "SELECT TOP 5 id, name FROM Users"}}}

Server returns:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"},
  {"id": 3, "name": "Carol"},
  {"id": 4, "name": "Dave"},
  {"id": 5, "name": "Eve"}
]

explain_query

Agent calls:

{"method": "tools/call", "params": {"name": "explain_query", "arguments": {"sql": "SELECT * FROM Orders WHERE customer_id = 42"}}}

Server returns:

{
  "estimatedTotalCost": 0.0033,
  "missingIndexes": [],
  "warnings": [],
  "topOperations": [
    {"operation": "Index Seek", "estimatedCost": 0.0033, "estimatedRows": 1, "object": "AppDb.dbo.Orders.PK_Orders"}
  ]
}

analyze_db_health

Agent calls:

{"method": "tools/call", "params": {"name": "analyze_db_health", "arguments": {"database": "mydb"}}}

Server returns:

[
  {"check": "database_size", "size_mb": 2048, "log_mb": 256},
  {"check": "vlf", "vlf_count": 24},
  {"check": "index_fragmentation", "total_indexes": 150, "fragmented_gt_30pct": 12, "worst": "dbo.Orders (87%)"},
  {"check": "stats_staleness", "total_stats": 150, "stale_gt_7d": 3, "max_staleness_days": 14},
  {"check": "blocking", "blocked_sessions": 0}
]

Authentication

mssql-mcp uses the connection string you provide — it does not authenticate on its own. The connection string determines the auth mode.

SQL Server authentication (username + password)

Server=tcp:myserver.database.windows.net,1433;Database=mydb;User Id=sqladmin;Password=YourStrong!Passw0rd;Encrypt=True;TrustServerCertificate=False;

Windows Integrated Authentication

On Windows with .NET 10, Integrated Security=True uses the running process's Windows credentials:

Server=myserver;Database=mydb;Integrated Security=True;Encrypt=True;TrustServerCertificate=True;

This does not work from the self-contained Linux/macOS npm binary (no SSPI). For cross-platform, use SQL authentication.

Microsoft Entra ID — no longer supported

The application no longer includes Microsoft.Data.SqlClient.Extensions.Azure. Its supported versions pull in Microsoft.Identity.Client.NativeInterop, whose packaged license prohibits redistribution. Removing that integration avoids shipping the restricted component without downgrading SqlClient security fixes.

Connection strings using Authentication=Active Directory ... no longer work, including Default, Managed Identity, Service Principal, Interactive, and Device Code Flow. Configure SQL authentication instead, or Windows Integrated Authentication on Windows. The application does not acquire Entra tokens or provide a replacement credential chain.

Configuration

All runtime parameters are configurable via environment variable. Precedence: CLI flag (if present) > env var > hardcoded default. The single exception is MSSQL_CONNECTION_STRING, which takes precedence over --connection-string because secrets live in env, not argv.

Connection pooling: The server does not override SqlClient pool settings. Each operation owns and disposes its reader, command, and pooled connection; concurrent MCP requests can use separate connections. Set Max Pool Size and Connection Lifetime in MSSQL_CONNECTION_STRING when needed. The query timeout is a command timeout, not a bound on total request duration, pool waits, or retries. SHOWPLAN session cleanup has an independent five-second cooperative cancellation budget, including when the query timeout is unlimited; failed cleanup discards the affected pool.

Invalid values fail fast at startup with a clear [startup] error naming the var, the invalid value, and the accepted range. Unknown env vars are ignored (forward compatibility).

CLI reference

mssql-mcp --help prints the full usage block:

Usage: mssql-mcp [options]
  (no args)              Start the MCP stdio server (default)
  --version              Print version and exit
  --help, -h             Print this help and exit
  --validate             Test the SQL Server connection and exit
  --connection-string    SQL Server connection string (env: MSSQL_CONNECTION_STRING)
  --access-mode          restricted | unrestricted (default: restricted, env: MSSQL_ACCESS_MODE)
  --query-timeout        Per-query timeout in seconds (default: 30, env: MSSQL_QUERY_TIMEOUT)
  --log-level            trace | debug | info | warning | error | critical (default: info, env: MSSQL_LOG_LEVEL)

To update mssql-mcp:
  npm install -g @codegiveness/mssql-mcp@latest
  # or
  dotnet tool update -g codegiveness.mssql-mcp

Troubleshooting

Agent can't see the server

Symptom: your harness (Claude Desktop, Cursor, etc.) doesn't list mssql-mcp in its tools, or the agent says it can't find the server.

Diagnosis steps:

1. Check the config file path. Each harness looks for config in a specific location — see the examples under Supported clients and confirm against your installed client's documentation. A wrong path means the harness never reads your config.
2. Check JSON syntax. A missing comma, trailing comma, or unescaped quote silently breaks the config. Paste your JSON into a linter (e.g. python -m json.tool config.json) to check.
3. Restart the harness. Most harnesses read config only at startup. Fully quit (not just minimize) and reopen.
4. Check that npx is on the harness's PATH. Some harnesses don't inherit your shell's PATH. If npx isn't found, use the absolute path (run which npx to find it) or switch to dotnet tool install and use "command": "mssql-mcp".
5. Check harness logs — see Per-harness log locations below.

Connection failed / login failed

Symptom: --validate prints [startup] Connection validation failed [connection]: ... or [startup] Connection validation failed [auth]: ....

Common fixes:

• Encrypt=True is required. Modern SqlClient defaults to Encrypt=True. If your server uses a self-signed certificate (common for on-prem SQL Server), also add TrustServerCertificate=True. Without it you'll see a certificate tag error:

  textCopy

  [startup] Connection validation failed [certificate]: The certificate chain was issued by an authority that is not trusted.
  

  Fix: add TrustServerCertificate=True to the connection string. For production Azure SQL, use TrustServerCertificate=False with a valid server certificate.

• Login failed (auth tag). Verify the User Id and Password. For Azure SQL, the username is usually admin@server (not domain\user). For on-prem SQL Server, check that SQL Server Authentication is enabled (it's off by default — enable it in SSMS > Server Properties > Security).

• Connection refused (connection tag). Check that:

  • The Server hostname is correct and resolvable.
  • SQL Server is running and accepts TCP connections (check SQL Server Configuration Manager > Protocols for <instance> > TCP/IP = Enabled).
  • Port 1433 (or your custom port) is reachable: telnet <server> 1433 or nc -zv <server> 1433.
  • Firewall rules allow the connection.

• Timeout (timeout tag). The default connection timeout is 15 seconds. If your server is slow or far away, add Connect Timeout=30 to the connection string.

Windows .NET runtime missing

Symptom: On Windows, npx -y @codegiveness/mssql-mcp --version fails with an error mentioning .NET or the runtime.

The Windows build is framework-dependent — it needs the .NET 10 runtime installed. Fix:

1. Install the .NET 10 runtime.
2. Verify: dotnet --version should print 10.x.x.
3. Re-run npx -y @codegiveness/mssql-mcp --version.

Alternatively, skip the runtime entirely by using the .NET tool:

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

Then use "command": "mssql-mcp" (instead of "command": "npx") in your harness config.

npm self-heal download failed

Symptom: The npm package's optional dependency for your platform wasn't installed (corporate mirror, --no-optional, etc.), and the shim's fallback download from GitHub Releases failed.

The shim prints the RID, the GitHub Releases URL, and the fallback command. Manual fix:

1. Download the archive for your platform from the GitHub Releases page (look for mssql-mcp-<version>-<rid>.tar.gz or .zip).
2. Extract it and note the path to the mssql-mcp (or mssql-mcp.exe) binary.
3. Option A — cache it where the shim expects:
   bashCopy

   mkdir -p ~/.mssql-mcp/bin/<version>/<rid>
   # Copy the extracted binary there, then:
   npx -y @codegiveness/mssql-mcp --version
   

   Replace <rid> with your platform RID from the platform matrix (e.g. linux-x64, osx-arm64).
4. Option B — use dotnet tool install -g codegiveness.mssql-mcp as the fallback (cross-platform, no download needed from GitHub Releases).
5. To skip the download attempt entirely, set MSSQL_MCP_NO_DOWNLOAD=1 in the environment. The shim will fail immediately instead of trying to download.

Per-harness log locations

When a harness fails to start the server, check its logs. The locations below are troubleshooting examples, not collected manual-verification records; paths and UI labels may vary by client version and operating system:

Tip: The server writes all its own logging to stderr. stdout is reserved for the MCP JSON-RPC protocol. If a harness captures stderr, you'll see [startup] messages and [tool] execution logs there. You can also set MSSQL_LOG_FILE=/tmp/mssql-mcp.log to write logs to a file for easier debugging.

Security

Default is read-only

In Restricted mode (the default), every execute_sql call is wrapped in BEGIN TRAN ... ROLLBACK. Even if an agent crafts a destructive statement, the Guard rejects it before it reaches SQL Server, and even if the Guard allowed it, the transaction would roll back. Defense in depth.

Guard layers

The Guard applies four layers of validation in Restricted mode:

1. AST allowlist — ScriptDom parses T-SQL; a visitor rejects non-SELECT statements and targeted dangerous constructs including INTO, NEXT VALUE FOR, OPENROWSET(BULK), EXECUTE, DDL and DML.
2. Rollback wrapper — accepted queries run inside BEGIN TRAN ... ROLLBACK. This defends against transactional effects, not arbitrary nontransactional/external effects or a Guard bypass. SQL grants remain the authorization boundary.
3. Command timeout — default 30s in Restricted mode; limits command execution, not total request duration or resource usage.
4. Byte-size safety net — results over 10 MB (configurable) are truncated with a notice appended, so an agent's context window isn't blown out.

Transaction rollback

In Unrestricted mode, the transaction wrapper is removed — that's what makes DML/DDL work. explain_query is still Guarded in both modes because it uses SET SHOWPLAN_XML ON and never executes the query.

Reporting vulnerabilities

See SECURITY.md. Do not open a public issue for security vulnerabilities — use GitHub's private vulnerability reporting.

Development

Prerequisites

• .NET SDK 10.0.401, pinned by global.json; stable patch roll-forward only, no previews
• Git
• (Optional) Docker — for integration tests against SQL Server
• Node 24 LTS or a compatible current release — for the locked Inspector/coverage tooling; the npm distribution shim itself supports Node 18+

Build and test

git clone https://github.com/codegiveness/mssql-mcp.git
cd mssql-mcp
dotnet restore mssql-mcp.sln
dotnet build mssql-mcp.sln
dotnet test --solution mssql-mcp.sln -- --filter-not-trait Category=Integration

Unit tests exclude the opt-in SQL integration cases. Load .env before local tests or --validate; keep it untracked.

Integration tests (requires live SQL Server)

# Start an isolated SQL Server container
docker run -e "ACCEPT_EULA=1" -e "MSSQL_SA_PASSWORD=YourStrong!Passw0rd" \
  -p 1433:1433 --name mssql-test -d mcr.microsoft.com/mssql/server:2022-latest

# Run integration tests
INTEGRATION=true MSSQL_CONNECTION_STRING="Server=localhost;User Id=sa;Password=YourStrong!Passw0rd;Encrypt=True;TrustServerCertificate=True;" dotnet test --solution mssql-mcp.sln

Integration tests are tagged [Trait("Category", "Integration")] and skipped by default.

npm smoke test

node npm/test.js

Verifies the shim (bin/mssql-mcp.js) parses, the RID mapping returns expected values for known platforms, and the checksum parser handles bare and sha256sum-formatted sidecar files. The real integration test is npm pack && npm install --ignore-scripts on each platform.

Release policy checks

node scripts/check-release-policy.js --manifest
node scripts/test/check-release-policy.test.js
node scripts/check-version-consistency.js
node scripts/test/check-version-consistency.test.js

The first command admits only a canonical 0.x version. The deterministic tests exercise valid 0.x tags, blocked majors (including v1 RCs), malformed tags, and the real manual-dispatch/manifest entrypoints without creating a release. CI applies the same guard to release PRs, automatic release-please releases, tag pushes, and manual dispatch before artifact publication.

Version consistency includes the main npm package's optional dependencies and all five platform package manifests, as well as the csproj and server.json. After a canonical manifest change, node scripts/sync-all-stamps.js synchronizes all these derivatives before release builds or preparing committed stamps. A stale platform version can otherwise make a local npm package install resolve a different registry version.

.NET baseline and tooling boundaries

The server, SQL execution, Guard, configuration, logging, and serialization run in C# 14 on net10.0. SDK 10.0.401 / runtime 10.0.12 are the latest stable .NET 10 releases verified against Microsoft's release metadata. Package versions are centralized in Directory.Packages.props; committed lockfiles cover portable builds and all six publish profiles. CI reads the same global.json, and Docker pins both SDK and runtime-dependency images by digest. Redistribution guard: the Azure authentication extension and its restricted Microsoft.Identity.Client.NativeInterop graph were removed with owner approval. Entra authentication is no longer supported; SQL password and Windows Integrated remain. node scripts/check-redistribution.js now admits the broker-free graph and continues to fail closed if that dependency is reintroduced. Release runs the guard before producing/publishing artifacts; CI applies it before NuGet/npm uploads. Native Windows SNI assets are explicitly excluded too. See Third-Party Notices. This guard does not establish general license compliance.

Non-.NET components serve distribution or independent verification, not a second server implementation: Node supports npm/npx installation, release-stamp tooling, and the official MCP Inspector; Python orchestrates content-pinned external security auditors; Bash coordinates CI/smoke/fuzz commands; native fuzzing tools supply coverage instrumentation. Replacing those integrations would not make SQL execution more .NET. The mandatory Inspector smoke uses its already-required Node runtime for JSON handling, so that command no longer needs Python.

# Build first so the smoke exercises current source, not an older local executable.
dotnet build mssql-mcp.sln
./scripts/mcp-smoke.sh

The smoke checks a real stdio handshake, nine-tool discovery, a successful list_databases result, and idempotency annotations. Detailed modernization measurements and verification limits are recorded in the engineering evidence.

Project layout

mssql-mcp.sln
src/
  mssql-mcp.Core/       # Guard, SqlExecutor, Options — no MCP deps
  mssql-mcp.Tools/      # 9 tool classes with [McpServerTool]
  mssql-mcp/            # App: Program.cs, DI, stdio, CLI, npm entrypoint
tests/
  mssql-mcp.Core.Tests/ # Guard AST validation, type coercion, etc.
  mssql-mcp.Tools.Tests/ # Tool attribute wiring, schema tests
npm/                    # npm package: bin shim + per-platform packages + smoke test
docs/adr/               # Architectural Decision Records

See CONTRIBUTING.md for coding standards, ADR workflow, and the PR process.

Trademarks & licensing

• License: MIT. See LICENSE and NOTICE.
• Third-party notices: See THIRD-PARTY-NOTICES.md for distributed components and the excluded Azure/native SNI dependencies.
• Not affiliated with Microsoft Corporation. "Microsoft SQL Server", "Windows", "Azure", "Microsoft Entra ID", and related marks are trademarks of Microsoft Corporation. This project is an independent MCP server that connects to SQL Server using the public Microsoft.Data.SqlClient ADO.NET provider.
• Client Access License (CAL) / multiplexing. Using mssql-mcp does not reduce or eliminate SQL Server licensing requirements. Each end user or device that indirectly accesses SQL Server through mssql-mcp may require a CAL or a Core-based license, exactly as if they were connecting directly. You are responsible for ensuring your SQL Server deployment is properly licensed.

Contributing

See CONTRIBUTING.md. PRs welcome — please open an issue first to discuss the scope of any non-trivial change.

Stability

mssql-mcp continues releasing in the 0.x series. There is no scheduled v1 release, RC promotion, or 30-day graduation requirement. Automatic and manual release workflows reject major versions >= 1 before publishing artifacts; see ADR-0036.

The tool surface remains stable (tool names, parameter names, and parameter types don't break within 0.x); CLI flags, env var names, error response shapes, and return value formats may change between minor versions. The former launch milestones (#1, #11, #20, #22, #34) are retired under the revised policy, not certified as passing their original tests. Guard, security, distribution, CI, and pre-push controls remain in force.

Architecture & decisions

Architectural Decision Records (ADRs) document every significant design choice. They live in docs/adr/. See the ADR index for all 36 ADRs. Key decisions:

• ADR-0006 — Guard AST allowlist
• ADR-0015 — Configuration via env vars (secrets in env, not argv)
• ADR-0028 — Binary delivery via optional dependencies and shim self-heal
• ADR-0033 — Branch protection posture for solo-maintained project
• ADR-0036 — Continue 0.x releases; distinguish production reports, stdio proof, and harness examples

For the consolidated security posture (OpenSSF Scorecard, SBOM, supply-chain attestation, branch protection), see docs/security-posture.md.