# SQL MCP server

> Enables AI agents to manage multiple SQL Server instances, perform index audits, analyze execution plans, and run queries across grouped connections.

- Repository: https://github.com/cvelasquez/mcp-sqlserver
- Page: https://hostedmcp.org/servers/cvelasquez/mcp-sqlserver
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 3.3.0

## Install

### Claude Code

```sh
claude mcp add --env 'MSSQL_MCP_CONNECTIONS_JSON=<YOUR_MSSQL_MCP_CONNECTIONS_JSON>' mcp-sqlserver -- npx -y @cevelas/mcp-sqlserver
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-sqlserver": {
      "command": "npx",
      "args": [
        "-y",
        "@cevelas/mcp-sqlserver"
      ],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "mcp-sqlserver": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@cevelas/mcp-sqlserver"
      ],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-sqlserver","type":"stdio","command":"npx","args":["-y","@cevelas/mcp-sqlserver"],"env":{"MSSQL_MCP_CONNECTIONS_JSON":"<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"}}'
```

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

```json
{
  "mcpServers": {
    "mcp-sqlserver": {
      "command": "npx",
      "args": [
        "-y",
        "@cevelas/mcp-sqlserver"
      ],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-sqlserver --env 'MSSQL_MCP_CONNECTIONS_JSON=<YOUR_MSSQL_MCP_CONNECTIONS_JSON>' -- npx -y @cevelas/mcp-sqlserver
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-sqlserver]
command = "npx"
args = ["-y", "@cevelas/mcp-sqlserver"]

[mcp_servers.mcp-sqlserver.env]
MSSQL_MCP_CONNECTIONS_JSON = "<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'MSSQL_MCP_CONNECTIONS_JSON=<YOUR_MSSQL_MCP_CONNECTIONS_JSON>' mcp-sqlserver npx -- -y @cevelas/mcp-sqlserver
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-sqlserver": {
      "command": "npx",
      "args": [
        "-y",
        "@cevelas/mcp-sqlserver"
      ],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "<YOUR_MSSQL_MCP_CONNECTIONS_JSON>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MSSQL_MCP_CONNECTIONS_JSON` | no | yes | The connections JSON inline, for setups that keep credentials out of the filesystem. |
| `MSSQL_MCP_CONNECTIONS` | no | no | Path to connections.json. Defaults to ~/.mcp-sqlserver/connections.json; create one with --init. |
| `MSSQL_TEST_CONNECTION` | no | no |  |

## Tools (8)

- `list_connections`
- `reload_connections`
- `query`
- `get_schema`
- `get_indexes`
- `get_execution_plan`
- `get_stored_procedure`
- `format`

## FAQ

### How do I manage multiple SQL Server connections?

Connections are stored in a single `connections.json` file, which can be grouped by client or environment and hot-reloaded without restarting the agent.

### What happens if a query returns too many rows?

The server caps results at 1000 rows by default (up to 10000 via maxRows) and will cancel the query on the server if the limit is hit to save context window space.