# mssql-mcp

MCP server for Microsoft SQL Server. Supports Windows Authentication and SQL Server Authentication via the native `msnodesqlv8` ODBC driver.

## Requirements

- Windows (native ODBC driver required)
- [ODBC Driver 17 or 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server)
- Node.js >= 18

The ODBC driver is auto-detected from the Windows registry — no configuration needed.

## Installation

```bash
npm install
npm run build
```

## Configuration

All configuration is via environment variables. No `.env` file is required when running via an MCP host — set `env` in the MCP config instead.

### Authentication

**Windows Authentication** (use the current Windows user — no credentials needed):

```
MSSQL_SERVER=myserver
```

**SQL Server Authentication** (provide both user and password):

```
MSSQL_SERVER=myserver
MSSQL_USER=sa
MSSQL_PASSWORD=secret
```

> Note: `MSSQL_USER` and `MSSQL_PASSWORD` must both be set or both be absent. Setting only one will throw an error.

### Multiple servers

Use `MSSQL_<KEY>_SERVER` to configure multiple servers. Each key becomes a selectable `dbKey` in the MCP tools.

**Windows auth on all servers:**
```
MSSQL_PROD_SERVER=prod-server
MSSQL_QA_SERVER=qa-server
MSSQL_DEV_SERVER=dev-server
```

**Mixed auth:**
```
MSSQL_PROD_SERVER=prod-server

MSSQL_DEV_SERVER=dev-server
MSSQL_DEV_USER=sa
MSSQL_DEV_PASSWORD=secret
```

Each key can also override the ODBC driver:
```
MSSQL_PROD_DRIVER=ODBC Driver 18 for SQL Server
```

Or set a global override for all servers:
```
MSSQL_DRIVER=ODBC Driver 17 for SQL Server
```

### Optional: port

```
MSSQL_PORT=1433
# or per-key: MSSQL_PROD_PORT=1433
```

## MCP Host Config

### Claude Desktop (`claude_desktop_config.json`)

**Single server — Windows auth:**
```json
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"],
      "env": {
        "MSSQL_SERVER": "your-server"
      }
    }
  }
}
```

**Single server — SQL auth:**
```json
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"],
      "env": {
        "MSSQL_SERVER": "your-server",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "secret"
      }
    }
  }
}
```

**Multiple servers:**
```json
{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"],
      "env": {
        "MSSQL_PROD_SERVER": "prod-server",
        "MSSQL_QA_SERVER": "qa-server",
        "MSSQL_DEV_SERVER": "dev-server",
        "MSSQL_DEV_USER": "sa",
        "MSSQL_DEV_PASSWORD": "secret"
      }
    }
  }
}
```

### VS Code (`mcp.json`)

```json
{
  "servers": {
    "mssql": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mssql-mcp/dist/index.js"],
      "env": {
        "MSSQL_SERVER": "your-server"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|---|---|
| `execute_sql` | Execute any SQL query |
| `list_tables` | List tables, optionally filtered by schema |
| `get_table_schema` | Get column definitions for a table |
| `list_databases` | List configured servers and their auth type |

When multiple servers are configured, each tool accepts a `dbKey` parameter to select the target server.

## Notes

- The LLM should use fully-qualified table names (e.g. `MyDatabase.dbo.Orders`) — no database selection is needed in config.
- Connection pools are created lazily on first use and reused across calls.