# 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](https://modelcontextprotocol.io).

**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)

## Quick start

```bash
# 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:

```bash
odbcinst -q -d
```

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

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

Install only the MCP server:

```bash
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:

```dotenv
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:

```bash
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](docs/configuration.md) for Windows
and Azure AD authentication, named instances, and additional connections.

Claude Desktop (`claude_desktop_config.json`):

```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](docs/client-configs.md)).

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

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

## Security model

| Mode (`SECURITY_MODE`) | Allows |
|---|---|
| `read_only` *(default)* | SELECT, metadata, resources, allowlisted procs |
| `standard` | + parameterized DML, procedures, transactions, imports |
| `elevated` | + DDL (CREATE/ALTER/DROP of schema objects) |

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](docs/security.md).

## Documentation

| | |
|---|---|
| [Installation](docs/installation.md) | [Configuration](docs/configuration.md) |
| [Windows setup](docs/windows-setup.md) | [Security guide](docs/security.md) |
| [Linux setup](docs/linux-setup.md) | [Troubleshooting](docs/troubleshooting.md) |
| [macOS setup](docs/macos-setup.md) | |
| [Docker guide](docs/docker.md) | [Tools reference](docs/tools-reference.md) |
| [Client configs](docs/client-configs.md) | [Example prompts](docs/example-prompts.md) |

## Development

```bash
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](LICENSE).