mssql-mcp-server

Production-ready, cross-platform Microsoft SQL Server MCP server — lets AI assistants (Claude Desktop, Cursor, VS Code, Windsurf, Continue, ...) work with SQL Server through the Model Context Protocol.

Security-first: read-only by default, AST-based SQL policy enforcement, dangerous statements blocked, parameterized queries only, secrets never logged.

Features

• 51 tools across 7 groups (registered according to your security policy):

  • Query: parameterized SELECT with pagination, DML, stored procedures, scalar/table functions, explicit transactions with idle auto-rollback, bulk insert

  • Metadata: databases, schemas, tables, views, procedures, functions, triggers, columns, indexes, foreign keys, constraints, sizes, schema search, object definitions

  • Admin (read-only, opt-in): active/blocking sessions, running queries, deadlocks, backup history, agent jobs, server info, index fragmentation, missing indexes, database health

  • AI helpers (deterministic): schema context for NL→SQL, validate/optimize/ fix SQL, execution plans, cost estimates, FK-path join generation

  • Export: CSV / Excel / JSON / Parquet (path-jailed, formula-injection safe)

  • Import: CSV with preview + type inference, bulk file load

  • Connections: multiple named connections, health checks, database switching

• 7 resources (mssql://...) and 8 prompts (query writing, tuning, schema walkthroughs, data-quality audits...)

• Connectivity: SQL auth, Windows auth, Azure AD (password / service principal / managed identity), named instances, custom ports, TLS, connection pooling

• Cross-platform: Windows (ODBC Driver 18), Ubuntu/Debian/RHEL/Rocky/Alma, macOS (Homebrew), Docker (stdio or streamable-HTTP)

Related MCP server: SQL Server MCP

Quick start

# Linux / macOS (installs the ODBC driver + the server)
./scripts/install.sh

# Windows (PowerShell, installs ODBC Driver 18 + the server)
./scripts/install.ps1

# or, with the driver already installed:
pipx install "mssql-mcp-server[dataio]"

If SQL Server is already installed

You do not need to start the bundled Docker database. The computer running the MCP server still needs:

• Python 3.12 or newer

• Microsoft ODBC Driver 18 for SQL Server

• Network access and valid credentials for the existing SQL Server

Verify the ODBC driver on Linux or macOS:

odbcinst -q -d

The output should include [ODBC Driver 18 for SQL Server]. On Windows, check from PowerShell with:

Get-OdbcDriver | Where-Object Name -eq "ODBC Driver 18 for SQL Server"

Install only the MCP server:

pipx install "mssql-mcp-server[dataio]"

Create a .env file in the directory where the MCP server will run and point it at the existing database:

MSSQL_SERVER=localhost
MSSQL_PORT=1433
MSSQL_DATABASE=your_database
MSSQL_AUTH=sql
MSSQL_USERNAME=your_username
MSSQL_PASSWORD=your_password
MSSQL_ENCRYPT=true
READ_ONLY=true

Then start the server:

mssql-mcp

Replace localhost with the SQL Server hostname or IP address when it is remote. For a local development server with a self-signed certificate, set MSSQL_TRUST_CERTIFICATE=true; do not use that setting for production. The default transport is stdio, so the command normally waits for an MCP client to communicate with it. See Configuration for Windows and Azure AD authentication, named instances, and additional connections.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mssql": {
      "command": "mssql-mcp",
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_DATABASE": "SampleShop",
        "MSSQL_USERNAME": "app_reader",
        "MSSQL_PASSWORD": "***",
        "READ_ONLY": "true"
      }
    }
  }
}

Claude Code users can install it as a plugin instead:

/plugin marketplace add deepesh112/mcp_tool_sql
/plugin install mssql-mcp@deepesh112-mssql

(uses uvx; connection comes from your MSSQL_* environment variables — see docs/client-configs.md).

Try the bundled dev stack (SQL Server 2022 + sample database + the server over HTTP):

docker compose -f docker/docker-compose.yml up --build

Security model

Dangerous operations (DROP DATABASE, xp_cmdshell, SHUTDOWN, KILL, TRUNCATE, login changes, OPENROWSET, BACKUP/RESTORE, GRANT/DENY/REVOKE, dynamic EXEC(...)) are blocked in every mode unless you set ALLOW_DANGEROUS_OPERATIONS=true and list the category in ALLOWED_DANGEROUS_OPS. Every statement is parsed (sqlglot AST) and scanned by a normalizing regex layer; unparseable statements are rejected (fail closed). Tools your policy forbids are never registered, so clients can't even see them. Details: docs/security.md.

Documentation

Development

uv venv && uv pip install -e ".[dev]"
pytest                          # unit + security (no DB needed)
pytest -m integration           # needs a live SQL Server (see docker/)
ruff check src tests && black --check src tests && mypy

License

MIT — see LICENSE.