SQL Server MCP

Requirements:.NET 8.0 or later runtime (the tool targetsnet8.0andnet10.0), SQL Server, and a connection string. Building from source requires the .NET 10.0 SDK.

SetMCPMSSQL_CONNECTION_STRINGand run the server in one of these ways:

# Option 1: Run from NuGet package (e.g. with MCP Inspector) export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;" npx -y @modelcontextprotocol/inspector dotnet dnx Alyio.McpMssql --prerelease

# Option 2: Install and run as a global tool dotnet tool install --global Alyio.McpMssql --prerelease export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;" npx -y @modelcontextprotocol/inspector mcp-mssql

# Option 3: Run from source (clone repo, then) export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;" npx -y @modelcontextprotocol/inspector dotnet run --project src/Alyio.McpMssql

Use--prereleasefor pre-release builds.

All settings use theMCPMSSQLprefix.Flatenvironment variables (e.g.MCPMSSQL_CONNECTION_STRING) are the straightforward way to configure thedefaultprofile when you have a single connection. For multiple profiles, the user-scopedappsettings.jsonfile is recommended.

Single connection:Configure via environment variables.

# Connection string (required). export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;" # Optional description for the default profile (tooling/AI discovery). export MCPMSSQL_DESCRIPTION="Primary connection" # Optional max rows per interactive query (default 500; hard ceiling 1000). export MCPMSSQL_QUERY_MAX_ROWS="500" # Optional query timeout in seconds (default 30). export MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS="60" # Optional max rows for snapshot queries (default 10000; hard ceiling 50000). export MCPMSSQL_QUERY_SNAPSHOT_MAX_ROWS="10000" # Optional snapshot query timeout in seconds (default 120). export MCPMSSQL_QUERY_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120" # Optional analyze timeout in seconds (default 300). export MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS="300" # Optional: enable write commands (DDL/DML) via run_command (default false). # Soft guard only — prefer a db_datareader login for a hard read-only guarantee. export MCPMSSQL_ALLOW_WRITE="false" # Optional write command timeout in seconds (default 60; hard ceiling 600). export MCPMSSQL_WRITE_COMMAND_TIMEOUT_SECONDS="60"

Multiple connections:Use the user-scopedappsettings.jsonfile (recommended). Env vars also work via .NET host conventions (MCPMSSQL__PROFILES__<NAME>__CONNECTIONSTRING, etc.).

- Unix-like:~/.config/mcp-mssql/appsettings.json
- Windows:%USERPROFILE%\.config\mcp-mssql\appsettings.json

{ "McpMssql": { "Profiles": { "default": { "ConnectionString": "Server=...;User ID=...;Password=...;", "Description": "Primary connection", "Query": { "MaxRows": 500, "CommandTimeoutSeconds": 60, "SnapshotMaxRows": 10000, "SnapshotCommandTimeoutSeconds": 120 }, "Analyze": { "CommandTimeoutSeconds": 300 } }, "warehouse": { "ConnectionString": "Server=warehouse.example.com;...", "Description": "Warehouse read-only" }, "migrations": { "ConnectionString": "Server=...;User ID=...;Password=...;", "Description": "Write-enabled profile for schema changes", "AllowWrite": true, "Write": { "CommandTimeoutSeconds": 60 } } } } }

Local development:Store the connection string in user-secrets, then run withDOTNET_ENVIRONMENT=Developmentso secrets load.

dotnet user-secrets set "MCPMSSQL_CONNECTION_STRING" "..." --project src/Alyio.McpMssql npx -y @modelcontextprotocol/inspector -e DOTNET_ENVIRONMENT=Development dotnet run --project src/Alyio.McpMssql

All tools accept an optionalprofile; when omitted, the default profile is used.

- kind—catalog,schema,relation, orroutine. Forget_object, onlyrelationorroutine.
- includes— Array of detail sections:columns,indexes,constraints(relations only),definition(routines only).

Resources mirror their corresponding tools and return JSON (exceptmssql://plans/{id}which returns XML andmssql://snapshots/{id}which returns CSV).

The query tools (run_query,analyze_query) are read-only (SELECTonly) and use parameterized@paramNamebinding. Use environment variables or user-secrets for connection strings—never commit secrets.

Writes are opt-in.Therun_commandtool executes arbitrary T-SQL. It is rejected unless the target profile setsAllowWrite=true, which defaults tofalse, so existing deployments stay read-only with no change. The tool is always advertised and rejects at call time on locked profiles.

AllowWriteis a soft, application-level guard,nota security boundary — it constrains this server, not the database. For a genuine read-only guarantee, connect with a login restricted todb_datareader, and keep write-enabled profiles pointed at credentials scoped to only what they need.run_commandis markeddestructivevia MCP tool annotations so hosts can gate it behind confirmation, but honor those annotations at the host's discretion.

Snippets for common MCP clients. Replace the connection string with your own; ensuredotnetis on your PATH. Theenvblock is not required if the connection string is already set viaappsettings.jsonor environment variables.