Mssql

MS SQL Server MCP Server v3.0.0

🚀 Model Context Protocol (MCP) server for Microsoft SQL Server - compatible with Claude Desktop, Cursor, Windsurf and VS Code.

Standards Alignment

• Protocol target: MCP draft/latest spec
• Transport spec: Transports
• Security: Security best practices
• SDK: @modelcontextprotocol/server / @modelcontextprotocol/client / @modelcontextprotocol/node v2 (2.0.0), targeting the 2026-07-28 MCP spec
• Requires Node.js >= 20

🚀 Quick Start

1. Install

npm install -g mssql-mcp

2. Configure IDE

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Cursor/Windsurf/VS Code (.vscode/mcp.json):

{
  "servers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

HTTP transport (remote/hosted scenarios):

{
  "servers": {
    "mssql": {
      "type": "http",
      "url": "http://127.0.0.1:3001",
      "env": {}
    }
  }
}

Replace with your actual database credentials. Credentials are read from the server environment only — never passed as tool parameters.

��️ Tool Catalog

Primary tools (use these)

All data tools accept a response_format parameter ("json" | "markdown", default "json"). Use "markdown" to get human-readable table output.

Deprecated aliases (still registered for backward compatibility)

These are the only alias tool names the server actually registers (in src/tools/*.ts). They behave the same as their replacement but are not documented in new integrations — use the primary tool names above instead.

🚌 Transport Modes

# stdio (default)
node dist/src/index.js

# HTTP on 127.0.0.1:3001
MCP_TRANSPORT=http node dist/src/index.js

# Custom HTTP host/port
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 node dist/src/index.js

🔧 Environment Variables

Database connection

Transport

🔒 Security Model

• No credential parameters: All connection settings come from environment variables only. Tool inputs cannot override connection config.
• Identifier validation: Schema, table, and procedure names are validated against a safe identifier pattern before interpolation into SQL.
• Parameterized queries: All user-supplied values (WHERE clause values, column values) must be passed as named parameters via @paramName — never embedded in query strings.
• Origin and Host validation: HTTP transport validates both the Origin and Host headers against an allowlist (localhost, [::1], and the configured bind host by default), guarding against DNS rebinding.
• SQL risk labeling: run_sql_query and execute_stored_procedure are explicitly labeled as non-read-only and open-world.

⚠️ SQL Risk Notes

run_sql_query accepts arbitrary SQL including DDL and DML. To minimize risk:

• Use a least-privilege SQL login (SELECT-only where possible)
• Never run the server with a sysadmin or sa account
• Consider network firewall rules to limit what the server can reach

📄 Pagination

All list tools return a pagination object:

{
  "count": 20,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "next_offset": 20,
  "total_count": 150
}

Default page size: 20 rows. Maximum: 200 rows.

Results are also truncated if the serialized payload exceeds 100KB, with a truncation_message explaining how many rows were dropped.

🏗️ Architecture

src/
  index.ts          ← bootstrap (env, transport selection)
  server.ts         ← createServer() factory
  constants.ts      ← limits, defaults, protocol strings
  config.ts         ← env parsing
  types.ts          ← shared TypeScript interfaces
  db/
    connection.ts   ← connection pool singleton
    validators.ts   ← SQL identifier validation
    query-builders.ts ← safe parameterized query construction
  tools/            ← one file per tool group
  resources/        ← MCP resource handlers
  transports/       ← stdio and HTTP transports
  utils/
    errors.ts       ← error normalization helpers
    format.ts       ← JSON formatting, payload truncation
    markdown.ts     ← markdown table/list rendering helpers
    pagination.ts   ← pagination metadata helpers

🧪 Inspector Smoke Test

npx @modelcontextprotocol/inspector

Expected:

• stdio server connects
• Tool list renders with all tools
• mssql_connection_status returns JSON without a connection
• mssql_connect_database works when env variables are set

🔨 Development

npm install
cp .env.example .env  # fill in your test DB credentials
npm run typecheck     # type check only
npm run build         # compile TypeScript
npm test              # run unit tests
npm run ci            # typecheck + build + test

License

MIT © BYMCS