MSSQL MCP Server

A production-ready Model Context Protocol (MCP) server for Microsoft SQL Server, built with Python + FastMCP.

Connect any MCP-compatible agent (Claude Desktop, Claude Code, etc.) directly to your MSSQL / Azure SQL instance and let it run queries, explore schemas, call stored procedures, and analyse execution plans — all through a structured, safe interface.

Features

| Category | Tools | |---|---| | Queries | execute_query — run any T-SQL; execute_in_transaction — atomic multi-statement batch | | Schema | list_databases, list_schemas, list_tables, describe_table | | Procedures | list_stored_procedures, get_stored_procedure_definition, execute_stored_procedure | | Analysis | get_execution_plan — estimated XML plan without running the query | | Resources | Read-only URI resources: mssql://databases, mssql://table/{db}/{schema}/{table}, etc. | | Prompts | prompt_sql_query, prompt_explore_schema, prompt_optimise_query |

Security built-in:

• MSSQL_READ_ONLY=true blocks all DML/DDL at the tool layer
• MSSQL_MAX_ROWS caps result-set size to prevent data exfiltration
• All queries use parameterised ODBC ? placeholders — no string interpolation for values
• Credentials never appear in logs

Prerequisites

1. Python 3.10+
2. Microsoft ODBC Driver 18 for SQL Server — download here
3. uv (recommended) or pip

Quick start

# 1. Clone / open the project
cd "MSSQL MCP"

# 2. Install with uv (recommended)
uv sync

# 3. Configure
cp .env.example .env
# Edit .env — set MSSQL_SERVER, MSSQL_USER, MSSQL_PASSWORD at minimum

# 4. Test with MCP Inspector
uv run mcp dev src/mssql_mcp/server.py

# 5. Or run directly
uv run mssql-mcp-server

Configuration

All settings are loaded from environment variables or a .env file in the working directory.

Connection

| Variable | Default | Description | |---|---|---| | MSSQL_SERVER | (required) | Server hostname, e.g. localhost, mydb.database.windows.net | | MSSQL_DATABASE | master | Default database | | MSSQL_PORT | 1433 | TCP port | | MSSQL_DRIVER | {ODBC Driver 18 for SQL Server} | ODBC driver name | | MSSQL_ENCRYPT | true | Encrypt TLS (recommended) | | MSSQL_TRUST_SERVER_CERTIFICATE | false | Trust self-signed certs (local dev only) |

Authentication

Set MSSQL_AUTH_TYPE to one of the modes below:

sql (default) — SQL Server login

MSSQL_AUTH_TYPE=sql
MSSQL_USER=myuser
MSSQL_PASSWORD=MyStr0ngP@ss!

windows — Windows / Integrated Authentication

MSSQL_AUTH_TYPE=windows

azure_ad_msi — Managed Identity (Azure-hosted workloads)

MSSQL_AUTH_TYPE=azure_ad_msi
# For user-assigned MI, add:
MSSQL_AZURE_CLIENT_ID=<managed-identity-client-id>

azure_ad_sp — Service Principal (CI/CD, non-Azure)

MSSQL_AUTH_TYPE=azure_ad_sp
MSSQL_AZURE_CLIENT_ID=<app-client-id>
MSSQL_AZURE_CLIENT_SECRET=<client-secret>
MSSQL_AZURE_TENANT_ID=<tenant-id>

Safety & behaviour

| Variable | Default | Description | |---|---|---| | MSSQL_READ_ONLY | false | Block all DML/DDL | | MSSQL_MAX_ROWS | 1000 | Row cap on SELECT results | | MSSQL_QUERY_TIMEOUT | 30 | Max query duration (seconds) | | MSSQL_POOL_MIN_SIZE | 2 | Min connection pool size | | MSSQL_POOL_MAX_SIZE | 10 | Max connection pool size |

Transport

| Variable | Default | Description | |---|---|---| | MSSQL_MCP_TRANSPORT | stdio | stdio or http | | MSSQL_MCP_HOST | 127.0.0.1 | Bind host (HTTP mode) | | MSSQL_MCP_PORT | 8000 | Bind port (HTTP mode) |

Claude Desktop integration

Add the following to your claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mssql": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\MSSQL MCP",
        "run",
        "mssql-mcp-server"
      ],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_DATABASE": "AdventureWorks",
        "MSSQL_AUTH_TYPE": "sql",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourStrong!Passw0rd",
        "MSSQL_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see the MSSQL tools in the tool picker.

Tool reference

execute_query

sql        (str)           T-SQL statement to run
database   (str, optional) Database override

Returns { success, columns, rows, row_count, truncated } for SELECT, or { success, rowcount } for DML/DDL.

execute_in_transaction

statements  (list[str])     Ordered list of T-SQL statements
database    (str, optional)

All statements commit together or roll back on first error.

list_databases

Returns all online databases with state, compatibility level, and creation date.

list_schemas

database  (str)

list_tables

database  (str)
schema    (str, optional)

Includes approximate row count and space used.

describe_table

table     (str)
schema    (str, default "dbo")
database  (str, optional)

Returns columns (with type/nullability/defaults/identity), primary key, foreign keys, and indexes.

list_stored_procedures

database  (str)
schema    (str, optional)

get_stored_procedure_definition

procedure_name  (str)
schema          (str, default "dbo")
database        (str, optional)

execute_stored_procedure

procedure_name  (str)             e.g. "dbo.usp_GetOrders"
params          (dict, optional)  {"@OrderId": 42}
database        (str, optional)

Returns the first result set.

get_execution_plan

sql       (str)
database  (str, optional)

Query is not executed — returns estimated XML plan only.

Development

# Install dev extras
uv sync --extra dev

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

# Tests
uv run pytest

# Interactive MCP Inspector
uv run mcp dev src/mssql_mcp/server.py

Project structure

MSSQL MCP/
├── pyproject.toml
├── .env.example
├── README.md
└── src/
    └── mssql_mcp/
        ├── server.py          ← FastMCP instance + entry point
        ├── config.py          ← pydantic-settings + DSN builder
        ├── db.py              ← aioodbc pool + fetch/execute helpers
        ├── tools/
        │   ├── query.py       ← execute_query, execute_in_transaction
        │   ├── schema.py      ← list_databases, list_schemas, list_tables, describe_table
        │   └── procedures.py  ← list/get/execute stored procedures, get_execution_plan
        ├── resources/
        │   └── schema.py      ← mssql:// URI resources
        └── prompts/
            └── sql.py         ← T-SQL generation and optimisation prompts

License

MIT