cvelasquez/mcp-sqlserver

One MCP entry, every SQL Server you administer. Connections live in a single
connections.json, grouped by client or environment, hot-reloaded without
restarting your AI agent — plus execution plans, index audits and
stored-procedure analysis.
Built for DBAs and consultants, not for a demo against a single localhost
database.
Install
Add this to your AI agent's MCP configuration:
Then create your connections file and restart the agent:
That writes ~/.mcp-sqlserver/connections.json from a commented template. Edit
it, and ask your agent to *"list all SQL Server connections"*.
Needs Node.js 22 or newer.
Where each agent keeps its MCP config
| Agent | Config file |
|---|---|
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Code | claude mcp add sqlserver -- npx -y @cevelas/mcp-sqlserver |
| VS Code / Copilot | .vscode/mcp.json |
| Cursor | ~/.cursor/mcp.json |
Any MCP-compatible agent works — ChatGPT, Gemini, Copilot, Cline, Zed and
others all take the same command / args pair.
Why this one
Most SQL Server MCP servers take a single connection string. That is fine for
one database. It falls apart when you administer thirty across eight clients,
because every instance needs its own entry in the agent config, its own
credentials, and its own restart when something changes.
| | Single-DSN servers | This one |
|---|---|---|
| Instances per MCP entry | 1 | all of them |
| Organised by client or environment | — | connectionGroup |
| Add or change a connection | edit agent config, restart | edit a file, reload_connections |
| Which server answered? | you assume | in every response's metadata |
| Beyond SELECT | — | execution plans, index layout, SP source |
| Read-only safety rail | — | "readOnly": true per connection |
Connections
| Field | Required | Notes |
|---|---|---|
| name | yes | Unique; this is what you say to the agent |
| server | yes | Hostname, IP, or host\instance |
| connectionGroup | no | Client, project or environment. Groups the listing |
| description | no | Shown in list_connections and in every response |
| database | no | Defaults to the login's default database |
| user, password | no | Omit for domain or Entra ID auth |
| port | no | Defaults to 1433 |
| encrypt, trustServerCertificate | no | encrypt defaults to true |
| readOnly | no | Rejects writing statements — see below |
Anything else you put here is passed straight to mssql,
so requestTimeout, connectionTimeout, pool, authentication and a nested
options object all work.
Keeping passwords out of the file
Any string may reference an environment variable:
A connection that references a variable you have not set is **disabled**, and
list_connections names both the connection and the missing variable. Leaving
the literal in place would only move the failure to connect time, where it
arrives as Login failed for user and tells you nothing.
You can also skip the file entirely and pass the whole thing through the agent
config, which keeps credentials in one place with the rest of your MCP secrets:
Where the file is looked for
In order, first hit wins:
1. --connections
2. $MSSQL_MCP_CONNECTIONS — a path
3. $MSSQL_MCP_CONNECTIONS_JSON — the JSON itself, inline
4. ./connections.json in the working directory
5. ~/.mcp-sqlserver/connections.json
6. connections.json next to the installed package
A path given explicitly via 1 or 2 that does not exist is an error — the server
will not quietly fall back to a different file and talk to the wrong database.
Checking every connection at once
Connects to every entry in parallel, runs SELECT 1, and lists which ones
fail and why. Exits non-zero if any did, so it works in a scheduled task.