SQL Server MCP Server

A Microsoft SQL Server MCP server that lets any MCP-compatible client (Claude Desktop, Cursor, etc.) interact with SQL Server databases via natural language.

This project is community-maintained and is not an official product of Microsoft.

Installation

From Source

git clone https://github.com/TocharianOU/sqlserver-mcp.git
cd sqlserver-mcp
npm install --ignore-scripts
npm run build

MCP Client Configuration

The server supports two transport modes:

| | Stdio | Streamable HTTP | |---|---|---| | Protocol | stdin/stdout | HTTP POST + SSE | | Suitable for | Local clients (Cursor, Claude Desktop) | Remote / multi-client deployments | | Health check | — | GET /health |

Mode 1 — Stdio (recommended for local use)

The client spawns the server process directly. No network port required.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["/absolute/path/to/sqlserver-mcp/dist/index.js"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "your_user",
        "SQLSERVER_PASSWORD": "your_password",
        "SQLSERVER_DATABASE": "your_database",
        "SQLSERVER_TRUST_CERT": "true"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["/absolute/path/to/sqlserver-mcp/dist/index.js"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "your_user",
        "SQLSERVER_PASSWORD": "your_password",
        "SQLSERVER_DATABASE": "your_database",
        "SQLSERVER_TRUST_CERT": "true"
      }
    }
  }
}

Enable write operations (optional)

Add SQLSERVER_ALLOW_WRITE=true to unlock the execute_write tool:

"env": {
  "SQLSERVER_HOST": "localhost",
  "SQLSERVER_USER": "your_user",
  "SQLSERVER_PASSWORD": "your_password",
  "SQLSERVER_ALLOW_WRITE": "true"
}

Mode 2 — Streamable HTTP

Start the server as a standalone HTTP process, then point clients at it.

Start the server

SQLSERVER_HOST=localhost \
SQLSERVER_USER=sa \
SQLSERVER_PASSWORD=your_password \
SQLSERVER_DATABASE=your_db \
SQLSERVER_TRUST_CERT=true \
MCP_TRANSPORT=http \
MCP_HTTP_PORT=3002 \
MCP_HTTP_HOST=0.0.0.0 \
node /absolute/path/to/sqlserver-mcp/dist/index.js

Verify it's running:

curl http://localhost:3002/health
# {"status":"ok","transport":"streamable-http","server":"sqlserver-mcp"}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "sqlserver": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "sqlserver": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

Note: In HTTP mode, each client connection creates a session identified by mcp-session-id. Sessions are cleaned up automatically on disconnect.

Available Tools

| Tool | Read/Write | Description | |------|-----------|-------------| | list_databases | Read | All ONLINE databases on the SQL Server instance | | list_tables | Read | Base tables in a database / schema with catalog info | | list_views | Read | Views with optional definition SQL text | | describe_table | Read | Full column definitions: type, length, precision, nullability, default | | show_indexes | Read | All indexes on a table: type, columns, uniqueness, disabled status | | get_foreign_keys | Read | FK relationships with delete/update rules (table or whole DB) | | execute_query | Read | Execute T-SQL SELECT / WITH CTE, returns columns + rows + timing | | execute_write | Write | INSERT / UPDATE / DELETE / MERGE — requires SQLSERVER_ALLOW_WRITE=true | | explain_query | Read | Estimated execution plan via SET SHOWPLAN_ALL | | get_table_stats | Read | Row counts, data size, index size per table (KB) | | get_server_info | Read | Version, edition, collation, clustering status | | test_connection | Read | Connectivity + permission checks with timing |

Configuration Reference

| Variable | Default | Description | |----------|---------|-------------| | SQLSERVER_HOST | localhost | SQL Server hostname or IP | | SQLSERVER_PORT | 1433 | SQL Server port | | SQLSERVER_USER | (required) | SQL Server login username | | SQLSERVER_PASSWORD | (required) | SQL Server login password | | SQLSERVER_DATABASE | (none) | Default database (optional) | | SQLSERVER_ENCRYPT | true | Encrypt the connection (recommended) | | SQLSERVER_TRUST_CERT | false | Trust self-signed cert — set true for local/dev only | | SQLSERVER_ALLOW_WRITE | false | Enable execute_write tool | | SQLSERVER_MAX_ROWS | 1000 | Row cap for execute_query results | | SQLSERVER_CONNECTION_TIMEOUT | 30000 | Connection timeout (ms) | | SQLSERVER_REQUEST_TIMEOUT | 60000 | Query timeout (ms) | | SQLSERVER_POOL_MAX | 10 | Max pool connections | | SQLSERVER_POOL_MIN | 0 | Min pool connections | | SQLSERVER_POOL_IDLE_TIMEOUT | 30000 | Idle connection timeout (ms) | | MCP_TRANSPORT | stdio | Transport mode: stdio or http | | MCP_HTTP_PORT | 3002 | HTTP listen port (HTTP mode only) | | MCP_HTTP_HOST | localhost | HTTP listen host (HTTP mode only) |

Security Notes

• The server is read-only by default. Only set SQLSERVER_ALLOW_WRITE=true when explicitly needed.
• Use a dedicated SQL Server login with the minimum required permissions (db_datareader for read-only).
• Always keep SQLSERVER_ENCRYPT=true in production. Only set SQLSERVER_TRUST_CERT=true for local development with self-signed certificates.
• In HTTP mode, place the server behind a reverse proxy with authentication for production use.

License

Apache-2.0 — see LICENSE for details.

Copyright (c) 2024 TocharianOU Contributors