mssql-mcp

library2.3.2jsnpmunverified

MCP server for Microsoft SQL Server integration with Claude Desktop, Cursor, Windsurf, and VS Code. Stable v2.3.2, actively maintained. Key differentiator: allows Claude to directly execute SQL queries, list schema objects, describe tables, read rows, and run stored procedures. Uses environment variables for credentials (never passed as tool parameters). Supports both stdio (npx) and HTTP transport. Deprecated legacy tool names are gradually being phased out. Requires Node >=18.0.0.

database

npm install mssql-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MSSQL-MCP

mssql-mcp

databasejavascriptv2.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mssql-mcp

✓ npx -y mssql-mcp@latest

Run as an MCP server via npx; no code import required. Use global install only for local testing.

MCP Server

✓ Configuration in claude_desktop_config.json or .vscode/mcp.json

Configure as an MCP server tool, not a library import.

HTTP transport

✓ Set type: 'http' and url in mcp.json for remote hosting

HTTP transport is optional; default is stdio via npx.

MCP server configuration for Claude Desktop shows environment-based authentication required for SQL Server.

// Add to claude_desktop_config.json or .vscode/mcp.json: // JSON configuration for MS SQL Server MCP server { "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" } } } }

Debug

Known issues

breakingTool names changed between v2.0 and v2.3: Old names like execute_query, get_schema, describe_table are deprecated and will be removed in v3. Use prefixed names (mssql_run_sql_query, etc.)

fix

Update tool calls to use the new mssql_ prefixed names (e.g., mssql_run_sql_query instead of execute_query).

affects: <2.3.0

deprecatedDeprecated tool aliases (execute_query, get_schema, etc.) still work but emit warnings. They will be removed in v3.

fix

Migrate to the new mssql_ prefix tools (e.g., mssql_run_sql_query).

affects: >=2.0.0,<3.0.0

gotchaCredentials are only read from environment variables at server startup, not from tool call parameters. Never pass DB_PASSWORD etc. as arguments.

fix

Set DB_* environment variables in the MCP server configuration. Validate environment before starting.

affects: >=2.0.0

gotchamssql_run_sql_query is NOT read-only; it can modify data. Always verify SQL before execution.

fix

Use mssql_read_table_rows for read-only access when possible.

affects: >=2.0.0

gotchaConnection must be established with mssql_connect_database before other tools work. The server does not auto-connect.

fix

Call mssql_connect_database first after server starts.

affects: >=2.0.0

breakingNode.js >=18.0.0 required. Older versions may fail to install or run.

fix

Upgrade Node.js to >=18.0.0.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mssql'

Missing optional dependency 'mssql' when using npx without npm install

fix

Use 'npx -y mssql-mcp@latest' or install globally with 'npm install -g mssql-mcp'

Error: Connection refused: connect ECONNREFUSED xxx.xxx.xxx.xxx:1433

SQL Server not running, firewall blocking, or wrong server address in DB_SERVER

fix

Check DB_SERVER and port (default 1433). Ensure SQL Server allows remote connections and TCP/IP is enabled.

Invalid DB_USER or DB_PASSWORD, or SQL Authentication not enabled on server

fix

Verify credentials in environment variables. Enable 'SQL Server and Windows Authentication mode' in SQL Server.

Upgrade

Version history

2.3.2latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredPinned to 1.28.0 for MCP protocol support

mssqlrequiredMicrosoft SQL Server client driver

tediousrequiredTDS driver for SQL Server (used by mssql)

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/BYMCS/mssql-mcp ↗

packagemssql-mcp ↗

homepagehttps://github.com/BYMCS/mssql-mcp#readme ↗