mcp-sqlserver

A powerful Model Context Protocol (MCP) server for Microsoft SQL Server. Connects AI assistants (Claude, Gemini, Kiro, OpenAI, Copilot, Cursor) directly to your SQL Server databases with enterprise-grade security controls.

37 tools across 6 categories: schema discovery, query execution, DDL, stored procedures, performance/DBA diagnostics, and developer utilities.

Changelog: See CHANGELOG.md for version history or GitHub Releases for detailed release notes.

What's New in v1.2

16 new tools — DBA diagnostics, code generation, ER diagrams, schema diff, data sampling, and more
SQL injection protection — All queries now use parameterized inputs and escaped identifiers
ISO date formatting — Dates display as 2025-01-27 instead of raw JavaScript Date strings
Streamable HTTP transport — Host the MCP server remotely with --http <port>
Health check — Verify connection status and server responsiveness

Features

Schema Discovery (9 tools)

Tool	Description
`list_databases`	List all accessible databases on the instance
`list_schemas`	List schemas in a database
`list_tables`	List tables with row counts and sizes
`list_views`	List views in a database
`describe_table`	Detailed column info: types, defaults, nullability, identity, computed
`get_foreign_keys`	Foreign key relationships for a table
`get_indexes`	Index information with included columns
`get_constraints`	PK, unique, check, and default constraints
`get_triggers`	Trigger definitions on a table

Query Execution (3 tools)

Tool	Description
`execute_query`	Run SELECT queries with automatic row limits
`execute_mutation`	Run INSERT/UPDATE/DELETE/MERGE (requires `readwrite` mode)
`export_query`	Export query results as CSV or JSON format

DDL Operations (1 tool)

Tool	Description
`execute_ddl`	Run CREATE/ALTER/DROP statements (requires `admin` mode)

Stored Procedures (3 tools)

Tool	Description
`list_procedures`	List stored procedures in a database
`describe_procedure`	View parameters and source code of a procedure
`execute_procedure`	Execute with named parameters (requires `readwrite` mode)

Performance & DBA (16 tools)

Tool	Description
`get_query_plan`	Estimated execution plan for any query
`get_active_queries`	Currently running queries from `sys.dm_exec_requests`
`get_table_stats`	Row count, total/used/unused size, and fragmentation %
`get_index_usage`	Index seeks, scans, lookups, and update statistics
`get_missing_indexes`	Missing index suggestions with ready-to-use CREATE INDEX DDL
`get_server_info`	Server version, edition, CPU count, memory, uptime
`get_database_info`	Database size, file layout, status, recovery model, object counts
`get_wait_stats`	Top server wait statistics — identifies CPU, I/O, lock bottlenecks
`get_deadlocks`	Recent deadlock events from the `system_health` Extended Events session
`get_blocking_chains`	Current blocking chains — which sessions are blocking others
`get_long_transactions`	Long-running open transactions that may be holding locks
`get_space_usage`	Detailed disk space usage by table (data, index, unused)
`get_backup_history`	Recent backup history: type, size, duration, device path
`get_query_store_stats`	Top resource-consuming queries from Query Store (SQL Server 2016+) — sortable by CPU, duration, reads, writes, or executions
`rebuild_index`	Rebuild or reorganize a fragmented index (requires `admin` mode)
`health_check`	Connection health check with latency, version, active sessions

Developer Utilities (6 tools)

`compare_schemas` — Schema Diff

Compare two databases side-by-side. Shows tables, columns, and type differences — perfect for dev vs prod comparison.

compare_schemas(source_database: "DevDB", target_database: "ProdDB")

Output includes: tables only in source/target, columns only in source/target, and column type/nullability differences.

`generate_code` — Code Generation

Generate typed code from any table's schema:

TypeScript — interfaces with proper types (number, string, Date, Buffer | null)
C# — classes with nullable value types (int?, DateTime?, decimal?)
SQL — CREATE TABLE scripts with full column definitions

generate_code(table: "Products", language: "typescript")
→ export interface Products {
    productId: number;
    productName: string;
    unitPrice: number | null;
    ...
  }

`generate_insert_scripts` — Data Export as INSERT

Generate INSERT statements from existing table data — useful for migration scripts, seed data, or backing up small reference tables.

generate_insert_scripts(table: "Categories", top: 10)
→ INSERT INTO [dbo].[Categories] ([CategoryName], [Description]) VALUES (N'Beverages', N'Soft drinks...');

`generate_er_diagram` — ER Diagram

Generate a Mermaid ER diagram from foreign key relationships. Paste the output into any Mermaid-compatible renderer (GitHub, Notion, VS Code, etc.).

generate_er_diagram(database: "Northwind")
→ erDiagram
    Products }o--|| Categories : "CategoryID"
    Products }o--|| Suppliers : "SupplierID"
    Orders }o--|| Customers : "CustomerID"
    ...

`generate_test_data` — Test Data Generation

Generate realistic INSERT statements with fake data based on column names and types. Smart heuristics for common patterns (email, phone, name, city, price, etc.).

generate_test_data(table: "Customers", count: 5)
→ INSERT INTO [dbo].[Customers] (...) VALUES (N'Alice', N'user1@example.com', N'New York', ...);

`sample_table` — Random Sampling

Get a random sample of rows from any table using NEWID() — useful for AI assistants to understand data patterns without scanning entire tables.

sample_table(table: "Orders", count: 5)

Security

Three Security Modes

Mode	SELECT	INSERT/UPDATE/DELETE	DDL	Stored Procedures
`readonly`	Yes	No	No	Read-only (list/describe)
`readwrite`	Yes	Yes	No	Full (execute)
`admin`	Yes	Yes	Yes	Full (execute)

SQL Injection Protection

All user-provided values are passed as parameterized query inputs (@param). Object identifiers (database, schema, table names) are escaped using SQL Server bracket notation ([name] with ] → ]]).

Additional Security Features

Database and schema allow/block lists
Automatic row count limits (configurable maxRowCount)
Blocked keyword detection (xp_cmdshell, SHUTDOWN, DROP DATABASE, etc.)
Column-level data masking for PII protection
Query type validation per security mode

Data Masking

Mask sensitive columns in query results:

security:
  maskColumns:
    - pattern: "*.password"
      mask: "***"
    - pattern: "*.ssn"
      mask: "XXX-XX-XXXX"
    - pattern: "dbo.users.email"
      mask: "***@***.***"

Pattern format: [schema.]table.column (use * as wildcard)

Authentication

Method	Config `type`	Requirements
SQL Server	`sql`	`user` + `password`
Windows (NTLM)	`windows`	`user` + `password` + optional `domain`
Windows (SSPI)	`windows`	No credentials needed; requires `msnodesqlv8`
Azure AD	`azure-ad`	`clientId` + `clientSecret` + `tenantId`

Windows Authentication

NTLM — Works out of the box, no extra packages:

connection:
  host: YOUR_SERVER\SQLEXPRESS
  authentication:
    type: windows
    user: YourUsername
    password: YourPassword
    domain: YOUR_DOMAIN
  trustServerCertificate: true

SSPI / Integrated Security — Uses current Windows login session:

npm install msnodesqlv8

connection:
  host: YOUR_SERVER\SQLEXPRESS
  authentication:
    type: windows
  trustServerCertificate: true

Note: When using npx, optional dependencies like msnodesqlv8 may not be installed automatically. For SSPI, consider installing globally (npm install -g @tugberkgunver/mcp-sqlserver msnodesqlv8) or use NTLM mode instead.

Transport

stdio (Default)

Standard input/output transport — used by MCP clients like Claude Desktop, VS Code, Cursor, etc.

Streamable HTTP

For remote hosting or web integrations:

mcp-sqlserver --config mssql-mcp.yaml --http 3000

This starts:

MCP endpoint: http://localhost:3000/mcp
Health check: http://localhost:3000/health → {"status":"ok","mode":"readonly"}

Includes CORS support for browser-based clients.

Quick Start

Install

npm install -g @tugberkgunver/mcp-sqlserver

Configure

Create mssql-mcp.yaml in your working directory:

connection:
  host: localhost
  port: 1433
  database: MyDatabase
  authentication:
    type: sql
    user: sa
    password: YourPassword123
  trustServerCertificate: true

security:
  mode: readonly
  maxRowCount: 1000
  blockedDatabases:
    - master
    - msdb
    - tempdb
    - model

See config.example.yaml for all options.

MCP Client Configuration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

With a config file:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver", "--config", "/path/to/mssql-mcp.yaml"]
    }
  }
}

VS Code (Copilot / Continue)

Add to .vscode/mcp.json:

{
  "servers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

OpenAI (ChatGPT Desktop)

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@tugberkgunver/mcp-sqlserver"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_DATABASE": "MyDatabase",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "YourPassword123"
      }
    }
  }
}

Windows (all clients)

On Windows, use cmd as the command wrapper:

{
  "mcpServers": {
    "mssql": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@tugberkgunver/mcp-sqlserver", "--config", "path/to/config.yaml"]
    }
  }
}

Environment Variables

Variable	Description
`MSSQL_HOST`	SQL Server hostname
`MSSQL_PORT`	SQL Server port (default: 1433)
`MSSQL_DATABASE`	Default database
`MSSQL_USER`	SQL auth username
`MSSQL_PASSWORD`	SQL auth password
`MSSQL_MCP_CONFIG`	Path to YAML config file

Environment variables override config file values.

Development

git clone https://github.com/gunvertugberk/mcp-sqlserver.git
cd mcp-sqlserver
npm install
npm run build
npm start -- --config ./mssql-mcp.yaml

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
config.example.yaml		config.example.yaml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

mcp-sqlserver

What's New in v1.2

Features

Schema Discovery (9 tools)

Query Execution (3 tools)

DDL Operations (1 tool)

Stored Procedures (3 tools)

Performance & DBA (16 tools)

Developer Utilities (6 tools)

compare_schemas — Schema Diff

generate_code — Code Generation

generate_insert_scripts — Data Export as INSERT

generate_er_diagram — ER Diagram

generate_test_data — Test Data Generation

sample_table — Random Sampling

Security

Three Security Modes

SQL Injection Protection

Additional Security Features

Data Masking

Authentication

Windows Authentication

Transport

stdio (Default)

Streamable HTTP

Quick Start

Install

Configure

MCP Client Configuration

Environment Variables

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`compare_schemas` — Schema Diff

`generate_code` — Code Generation

`generate_insert_scripts` — Data Export as INSERT

`generate_er_diagram` — ER Diagram

`generate_test_data` — Test Data Generation

`sample_table` — Random Sampling

Packages