SQL Server MCP for people who manage dozens of instances

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:

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"]
    }
  }
}

Then create your connections file and restart the agent:

npx -y @cevelas/mcp-sqlserver --init

That writes ~/.mcp-sqlserver/connections.json from a commented template. Edit it, and ask your agent to "list all SQL Server connections".

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.

Connections

{
  "connections": [
    {
      "name": "acme-prod",
      "connectionGroup": "Acme Corp",
      "description": "Production - head office",
      "server": "192.168.1.10\\SQLEXPRESS",
      "database": "AcmeDB_Prod",
      "user": "app_reader",
      "password": "${env:ACME_PROD_PASSWORD}",
      "port": 1433,
      "encrypt": true,
      "trustServerCertificate": false,
      "readOnly": true
    }
  ]
}

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:

"password": "${env:ACME_PROD_PASSWORD}"

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:

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "{\"connections\":[{\"name\":\"prod\",\"server\":\"10.0.0.1\",\"database\":\"App\",\"user\":\"reader\",\"password\":\"...\"}]}"
      }
    }
  }
}

Where the file is looked for

In order, first hit wins:

1. --connections <path>
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

npx -y @cevelas/mcp-sqlserver --check

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. Useful after a password rotation, or before blaming the agent.

Windows domain and Entra ID authentication

The bundled tedious driver supports NTLM and the Entra ID (Azure AD) family. Add domain for NTLM:

{
  "name": "warehouse",
  "server": "dwh.corp.local",
  "database": "DWH",
  "domain": "CORP",
  "user": "svc_analytics",
  "password": "${env:DWH_PASSWORD}"
}

{
  "name": "azure-sql",
  "server": "myserver.database.windows.net",
  "database": "reporting",
  "encrypt": true,
  "authentication": {
    "type": "azure-active-directory-password",
    "options": { "userName": "${env:AZURE_USER}", "password": "${env:AZURE_PASSWORD}" }
  }
}

Fully integrated auth — a trusted connection with no password at all — needs the native msnodesqlv8 driver, which is not bundled because it would break the one-line install on machines without a build toolchain. NTLM with an explicit service account is the supported path.

Tools

Every response carries the connection it came from:

{
  "metadata": {
    "connection": "acme-prod",
    "connectionGroup": "Acme Corp",
    "description": "Production - head office",
    "server": "192.168.1.10\\SQLEXPRESS",
    "database": "AcmeDB_Prod"
  },
  "data": [ ... ]
}

With thirty connections in play, that line is what tells you the answer came from the client you meant.

Query results that fit in a context window

An agent that runs SELECT * FROM Orders does not need four million rows, and neither does its context window.

• Row cap. query returns at most 1000 rows across all result sets. maxRows changes that, up to 10000. When the cap is hit the query is cancelled on the server, not trimmed afterwards.
• A truncated result says so, first. The response opens with "truncated": true and a note stating that more rows exist, that the total is unknown, and how to get it. It sits before the rows on purpose: a 10000-row response runs to hundreds of KB, and a client that cuts long output keeps the beginning. An agent must never conclude "the table has 10000 rows" from a capped result. Asking for more than 10000 is not an error — the cap is lowered to 10000, and if rows were left out the note says what was asked for.
• format: "csv". JSON repeats every column name on every row. With csv the response is one JSON header line with the metadata, a blank line, then the rows. NULL is an empty cell and an empty string is "", so the two stay distinguishable.
• Server messages. PRINT output and SET STATISTICS IO, TIME ON results come back in messages, so the agent can read logical reads and CPU time instead of guessing.
• Every result set. A batch with several SELECTs returns them all in recordsets. data is still the first one.
• Binary columns come back as hex (0x8f3a...), truncated after 64 bytes, instead of a JSON array with one number per byte.

rowCount is always present; truncated, messages and recordsets only appear when they have something to say. Responses are compact JSON.

What this gets you

Things that are tedious by hand and become one sentence to the agent:

• "Why is this stored procedure slow?" — get_stored_procedure for the source, get_execution_plan for the plan, get_indexes for what is missing.
• "Compare the Orders schema between acme-prod and acme-qa" — get_schema on both, agent diffs them.
• "Which indexes on this table are never covering anything?" — get_indexes plus the queries you care about.
• "I added a client to connections.json" — reload_connections, no restart.

Read-only connections

"readOnly": true