mssql MCP server

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

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 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:

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, or the Windows identity and database grants for Integrated Authentication.
certificate	TLS/SSL handshake failed	See Troubleshooting: connection / 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.

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.

Feature	mssql-mcp
Guardrails	AST validation + transaction rollback
Destructive SQL	Rejected by the Guard by default
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. 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.

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/reads from sys.dm_exec_query_stats.
analyze_db_health	Summary health check: size, VLFs, fragmentation, stats staleness, blocking.

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

list_databases

Parameter	Type	Required	Default	Description
(none)

Returns: JSON array of {name, is_current} objects (system DBs excluded).

list_schemas

Parameter	Type	Required	Default	Description
database	string	no	current db	Database to list schemas in (cross-DB-validated)

Returns: JSON array of {name, schema_id} objects.

list_objects

Parameter	Type	Required	Default	Max	Description
database	string	no	current db	—	Cross-DB-validated
schema	string	no	all	—	Filter by schema name
type	enum	no	all	—	TABLE, VIEW, PROCEDURE, FUNCTION
limit	int	no	1000	5000	Protects agent context window

Returns: JSON array of {name, schema, type} objects. Truncation notice prepended if limit hit.

get_object_details

Parameter	Type	Required	Default	Description
database	string	no	current db	Cross-DB-validated
schema	string	yes
name	string	yes
type	enum	no	auto	Same enum as list_objects

Returns: Columns, parameters, indexes, and triggers for the object. Returns OBJECT_NOT_FOUND error if no match.

execute_sql

Parameter	Type	Required	Description
sql	string	yes	Single T-SQL batch. Guard validates in Restricted mode.

Returns: JSON array of row objects (SELECT) or status objects (DML/DDL in Unrestricted mode).

explain_query

Parameter	Type	Required	Default	Description
sql	string	yes		The query to get an execution plan for
format	enum	no	summary	summary or xml

Returns: summary — JSON object with estimated cost, missing indexes, warnings, top 5 ops. xml — raw SHOWPLAN_XML. Never executes the query.

analyze_indexes

Parameter	Type	Required	Default	Description
database	string	no	current db	Cross-DB-validated
query	string	no	none	If provided, per-query analysis; if omitted, workload-wide

Returns: JSON array of missing-index recommendations from sys.dm_db_missing_index_* DMVs.

get_top_queries

Parameter	Type	Required	Default	Max	Description
database	string	no	current db	—	Cross-DB-validated
order_by	enum	no	avg_cpu	—	avg_cpu, total_cpu, avg_duration, total_duration, total_logical_reads, execution_count
limit	int	no	10	100

Returns: JSON array of top queries from sys.dm_exec_query_stats.

analyze_db_health

Parameter	Type	Required	Default	Description
database	string	no	current db	Cross-DB-validated

Returns: JSON array of 5 summary objects (size, VLF count, fragmentation, stats staleness, blocking).

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"}
  ]
}