MCP Server for Microsoft SQL Server

Production-oriented MCP server for Microsoft SQL Server, exposing database operations to MCP clients (Claude Desktop, VS Code Copilot, Cursor, and compatible hosts).

Features

• Query execution (SELECT, INSERT, UPDATE, DELETE), with an optional read-only mode (MSSQL_READ_ONLY=true)

• Database discovery and schema introspection

• Table metadata inspection (columns, types, nullability, defaults, PK)

• Index and foreign key discovery

• Environment-driven configuration for secure deployment

Related MCP server: SQL Query Tools MCP Server

Available Tools

Requirements

• Node.js 18+

• Access to a Microsoft SQL Server instance

• Network connectivity from MCP host to SQL Server (host:port)

Configuration

Set connection settings using environment variables:

* Required when MSSQL_AUTH_MODE=sql.

Note: the published Docker image always runs in http mode and does not build the msnodesqlv8 native driver (used only for MSSQL_AUTH_MODE=windows). Windows Authentication is only available when running the server directly on a Windows host via npx/npm start.

Read-only mode

Set MSSQL_READ_ONLY=true to restrict execute_query to read operations. When enabled:

• Only a single SELECT (or WITH ... SELECT) statement is accepted. Multiple statements, INSERT, UPDATE, DELETE, MERGE, TRUNCATE, DDL (CREATE/ALTER/DROP), GRANT/REVOKE/DENY, EXEC/EXECUTE, SELECT ... INTO, OPENROWSET/OPENQUERY/OPENDATASOURCE, and xp_*/sp_* procedures are rejected before reaching the database. Comments, string literals and delimited identifiers are ignored by the check.

• The query runs inside a transaction that is always rolled back.

• The connection is opened with ApplicationIntent=ReadOnly, which routes to a readable secondary replica when an Always On availability group with read-only routing is configured (it has no effect otherwise).

• The execute_query tool description exposed to the MCP client states that the server is read-only.

• The remaining tools (list_tables, describe_table, list_databases, get_table_indexes, get_foreign_keys) only read metadata and are unaffected.

This mode is a defense-in-depth measure, not a security boundary. The check is lexical and can reject legitimate queries that use a blocked word outside literals/identifiers (false positives), and T-SQL has enough syntax that bypasses cannot be fully ruled out. The effective guarantee must come from the database: use a login restricted to db_datareader (optionally with DENY INSERT, UPDATE, DELETE, ALTER, EXECUTE) and combine it with this flag.

Usage

Run directly from GitHub

npx github:ferronicardoso/mcp-mssqlserver

Claude Code (CLI)

claude mcp add mssqlserver --scope user -- npx -y github:ferronicardoso/mcp-mssqlserver

--scope controls where the server registration is stored:

Environment variables can be passed with repeated --env KEY=VALUE flags before the --, e.g.:

Bash (Linux/macOS/WSL):

claude mcp add mssqlserver --scope user \
  --env MSSQL_HOST=localhost \
  --env MSSQL_PORT=1433 \
  --env MSSQL_DATABASE=master \
  --env MSSQL_AUTH_MODE=sql \
  --env MSSQL_USER=sa \
  --env MSSQL_PASSWORD=your-password \
  -- npx -y github:ferronicardoso/mcp-mssqlserver

PowerShell:

claude mcp add mssqlserver --scope user `
  --env MSSQL_HOST=localhost `
  --env MSSQL_PORT=1433 `
  --env MSSQL_DATABASE=master `
  --env MSSQL_AUTH_MODE=sql `
  --env MSSQL_USER=sa `
  --env MSSQL_PASSWORD=your-password `
  -- npx -y github:ferronicardoso/mcp-mssqlserver

Codex CLI

Bash (Linux/macOS/WSL):

codex mcp add mssqlserver \
  --env MSSQL_AUTH_MODE=sql \
  --env MSSQL_HOST=localhost \
  --env MSSQL_PORT=1433 \
  --env MSSQL_DATABASE=master \
  --env MSSQL_USER=sa \
  --env MSSQL_PASSWORD=your-password \
  npx -- -y github:ferronicardoso/mcp-mssqlserver

PowerShell:

codex mcp add mssqlserver `
  --env MSSQL_AUTH_MODE=sql `
  --env MSSQL_HOST=localhost `
  --env MSSQL_PORT=1433 `
  --env MSSQL_DATABASE=master `
  --env MSSQL_USER=sa `
  --env MSSQL_PASSWORD=your-password `
  npx -- -y github:ferronicardoso/mcp-mssqlserver

For Windows Authentication instead, drop MSSQL_USER/MSSQL_PASSWORD and set MSSQL_AUTH_MODE=windows:

Bash (Linux/macOS/WSL):

codex mcp add mssqlserver \
  --env MSSQL_AUTH_MODE=windows \
  --env MSSQL_HOST=localhost \
  --env MSSQL_PORT=1433 \
  --env MSSQL_DATABASE=master \
  npx -- -y github:ferronicardoso/mcp-mssqlserver

PowerShell:

codex mcp add mssqlserver `
  --env MSSQL_AUTH_MODE=windows `
  --env MSSQL_HOST=localhost `
  --env MSSQL_PORT=1433 `
  --env MSSQL_DATABASE=master `
  npx -- -y github:ferronicardoso/mcp-mssqlserver

This registers the server in ~/.codex/config.toml. To remove it, run codex mcp remove mssqlserver.

Claude Desktop configuration

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "mssqlserver": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-mssqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_PORT": "1433",
        "MSSQL_DATABASE": "master",
        "MSSQL_AUTH_MODE": "sql",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your-password"
      }
    }
  }
}

VS Code MCP configuration

.vscode/mcp.json:

{
  "servers": {
    "mssqlserver": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-mssqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_PORT": "1433",
        "MSSQL_DATABASE": "master",
        "MSSQL_AUTH_MODE": "sql",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your-password"
      }
    }
  }
}

Run with Docker (HTTP transport)

The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint (e.g. from n8n's MCP Client Tool node or any Streamable HTTP-compatible client):

Bash (Linux/macOS/WSL):

docker run -d --name mcp-mssqlserver \
  -p 3001:3001 \
  -e MSSQL_HOST=host.docker.internal \
  -e MSSQL_PORT=1433 \
  -e MSSQL_DATABASE=master \
  -e MSSQL_AUTH_MODE=sql \
  -e MSSQL_USER=sa \
  -e MSSQL_PASSWORD=your-password \
  ghcr.io/ferronicardoso/mcp-mssqlserver:latest

PowerShell:

docker run -d --name mcp-mssqlserver `
  -p 3001:3001 `
  -e MSSQL_HOST=host.docker.internal `
  -e MSSQL_PORT=1433 `
  -e MSSQL_DATABASE=master `
  -e MSSQL_AUTH_MODE=sql `
  -e MSSQL_USER=sa `
  -e MSSQL_PASSWORD=your-password `
  ghcr.io/ferronicardoso/mcp-mssqlserver:latest

The MCP endpoint is then available at http://localhost:3001/mcp.

Local Development

git clone https://github.com/ferronicardoso/mcp-mssqlserver
cd mcp-mssqlserver
npm install
npm run build

Start the compiled server:

npm start

Build and Commit Workflow

This repository intentionally tracks dist/ to support npx github:user/repo usage.

The project uses a Husky pre-commit hook to:

1. build TypeScript (npm run build)

2. stage generated artifacts (git add dist)

Manual fallback:

npm run build
git add dist

Security Notes

• Never commit real credentials or .env files.

• Prefer least-privilege SQL users for production use. For read-only scenarios, use a db_datareader login in addition to MSSQL_READ_ONLY=true.

• For public or untrusted networks, enable encryption (MSSQL_ENCRYPT=true) and configure certificates appropriately.

Windows Authentication (Integrated Security)

To use Windows Authentication with Integrated Security (process account), configure:

MSSQL_AUTH_MODE=windows
MSSQL_HOST=sqlserver.company.local
MSSQL_PORT=1433
MSSQL_DATABASE=master

License

MIT © Raphael Augusto Ferroni Cardoso