Content
# mssql-mcp-server
[](LICENSE)
[](https://www.python.org/)
[](Dockerfile)
**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
```bash
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`)
```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
```bash
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`)
```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.
