mssql-mcp-server

A Microsoft SQL Server MCP server. Query, inspect, and troubleshoot any SQL Server instance from Cursor, Claude Code, Codex, or any MCP (Model Context Protocol) client. Connects via ODBC using per-caller credentials elicited at runtime. Passwords live only in server memory with an idle TTL and are never logged.

• Query tools: connect / disconnect / list_sessions session lifecycle, execute_sql with table/JSON/CSV output, and explain_query for estimated or actual Showplan XML execution plans
• Per-caller identity: the X-DB-User and X-DB-Password headers are both optional; anything missing is elicited once and cached in-memory
• Permission-scoped access: read vs. write is governed by the SQL login's own permissions; provision_mcp_read.sql provisions a ready-made read-only mcp_read login across all user databases
• Zero secrets on disk: no credentials in config files, env vars, or logs

Example prompts

• "Show the execution plan for this query and suggest a better index."
• "Who is blocking whom on db1 right now?"
• "List the 10 largest tables in the sales database."
• "Find all stored procedures that reference the Orders table."
• "Export the results of this query as CSV."

Tools

Tool	Description
connect	Open a session to a SQL Server database and return a session_id
disconnect	Close an active SQL Server session
list_sessions	List active sessions with server, database, and usage details
execute_sql	Run a SQL statement and return rows as table, JSON, or CSV
explain_query	Estimated or actual execution plan as Showplan XML

Quick Start

docker compose -f docker-compose.yml -p mssql-mcp up -d --build --force-recreate

Client setup

Both X-DB-User and X-DB-Password headers are optional: anything missing is prompted for once via MCP elicitation and cached in memory.

Cursor (mcp.json)

{
  "mcpServers": {
    "mssql-mcp": {
      "type": "http",
      "url": "http://localhost:8007/mcp",
      "headers": {
        "X-DB-User": "<your-db-username>",
        "X-DB-Password": "<your-db-password>"
      }
    }
  }
}

Claude Code

claude mcp add --transport http mssql-mcp http://localhost:8007/mcp \
  --header "X-DB-User: <your-db-username>" \
  --header "X-DB-Password: <your-db-password>"

Codex (~/.codex/config.toml)

[mcp_servers.mssql-mcp]
url = "http://localhost:8007/mcp"
http_headers = { "X-DB-User" = "<your-db-username>", "X-DB-Password" = "<your-db-password>" }

Any other MCP client works the same way: point it at the streamable HTTP endpoint and pass the headers.