mssql-mcp

MSSQL MCP Server

   

 

Experimental use only. This server is intended for education and evaluation, not production. Use a dedicated least-privilege SQL login and test all operations.

Overview

@eamonboyle/mssql-mcp exposes Microsoft SQL Server tools, resources, and prompts through the Model Context Protocol. The MCP client and its language model interpret natural-language requests and choose tools. This package validates requests, executes SQL Server operations, and returns structured results.

Key capabilities:

• Schema, object, relationship, dependency, and storage discovery
• Validated reads, parameterized searches, and estimated execution plans
• Insert, update, and delete tools with confirmation and row limits
• Preview tokens for update and delete operations
• DDL tools with an explicit configuration gate
• Multiple allowed databases on one SQL Server
• Local stdio and stateless Streamable HTTP transports

Supported clients include Cursor, VS Code, Claude Desktop, and other MCP-compatible hosts.

Quick start

Prerequisites

• Node.js 20 or newer
• Microsoft SQL Server
• An MCP-compatible client

The recommended installation runs the published package directly:

npx -y @eamonboyle/mssql-mcp

A global installation also exposes the mssql-mcp command:

npm install -g @eamonboyle/mssql-mcp
mssql-mcp

The one-click links use the minimal configuration shown below. Replace the sample connection values before use.

The badge payloads are generated from src/samples/claude_desktop_config.json. After changing the sample, run npm run docs:update-install-links; use npm run docs:check-install-links to verify they are current.

Minimal MCP configuration

The standard presets show connection placeholders and keep DDL disabled:

{
  "mcpServers": {
    "mssql-local": {
      "command": "npx",
      "args": ["-y", "@eamonboyle/mssql-mcp"],
      "env": {
        "SERVER_NAME": "localhost",
        "DATABASE_NAME": "AppDB",
        "DATABASES": "AppDB,ReportingDB",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "TRUST_SERVER_CERTIFICATE": "true",
        "READONLY": "false",
        "ENABLE_DDL": "false"
      }
    }
  }
}

Cursor uses mcpServers in ~/.cursor/mcp.json or .cursor/mcp.json. Claude Desktop uses the same shape in its configuration file.

Set ENABLE_DDL=true only when the assistant specifically needs to create or remove schema objects.

VS Code uses .vscode/mcp.json or its user MCP configuration with a top-level servers object:

{
  "servers": {
    "mssql-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@eamonboyle/mssql-mcp"],
      "env": {
        "SERVER_NAME": "localhost",
        "DATABASE_NAME": "AppDB",
        "DATABASES": "AppDB,ReportingDB",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "TRUST_SERVER_CERTIFICATE": "true",
        "READONLY": "false",
        "ENABLE_DDL": "false"
      }
    }
  }
}

See src/samples/ for copyable Claude Desktop and VS Code files. Do not commit configuration files containing real credentials.

Required configuration

The server validates these variables before starting. Missing or blank values produce an actionable startup error.

| Variable | Accepted format | Purpose | | -------------------------- | ---------------------- | --------------------------------------------------------------------- | | DB_USER | Nonblank string | SQL authentication username | | DB_PASSWORD | Nonblank string | SQL authentication password |

At least one database variable is required: set DATABASE_NAME, DATABASES, or both. With only DATABASE_NAME, that database is both the default and the allowlist. With only DATABASES, the first entry is the default. When both are set, DATABASE_NAME is used if it appears in DATABASES; otherwise the first allowed database is the runtime default.

Hostname and port

Do not include the port in SERVER_NAME. Values such as localhost,1434 are not supported by the Node.js mssql driver configuration used by this package. Set SERVER_NAME to the hostname and use SERVER_PORT separately.

{
  "SERVER_NAME": "localhost",
  "SERVER_PORT": "1434"
}

For a Docker port mapping such as:

ports:
  - "1434:1433"

use the published host port:

SERVER_NAME=localhost
SERVER_PORT=1434

The container still listens on 1433, but the MCP process connects through host port 1434.

Advanced configuration

Optional variables do not need empty placeholders. In-code defaults apply when they are absent.

| Variable | Accepted format | Default | Purpose | | ----------------------- | ----------------------------- | --------------------- | -------------------------------------------------------------- | | SERVER_NAME | Hostname | localhost | SQL Server hostname only | | SERVER_PORT | Integer from 1 to 65535 | Driver default 1433 | SQL Server TCP port; omitted from the driver config when unset | | ENCRYPT | "true" or "false" | "false" | Enable TLS encryption in the mssql driver | | TRUST_SERVER_CERTIFICATE | "true" or "false" | "true" | Trust the SQL Server certificate without validating its chain | | READONLY | "true" or "false" | "false" | Remove write and DDL tools when enabled | | ENABLE_DDL | "true" or "false" | "false" | Allow registered DDL tools to execute | | CONNECTION_TIMEOUT | Positive integer seconds | 30 | SQL Server connection timeout | | QUERY_TIMEOUT_MS | Positive integer milliseconds | 30000 | SQL request timeout | | MAX_ROWS | Positive integer | 10000 | Maximum rows returned by read tools | | MAX_WRITE_ROWS | Positive integer | 100 | Maximum rows one write operation may affect | | REQUIRE_WRITE_PREVIEW | "true" or "false" | "true" | Require a matching preview token for updates and deletes | | MCP_TRANSPORT | stdio or http | stdio | MCP transport mode | | MCP_HTTP_HOST | Host or IP string | 127.0.0.1 | Bind address for HTTP mode | | MCP_HTTP_PORT | Integer from 1 to 65535 | 3333 | Bind port for HTTP mode | | MCP_BASE_URL | Absolute HTTP or HTTPS URL | Unset | Public HTTP base advertised by the server; /mcp is appended |

Blank optional values use their documented defaults. Explicit nonblank invalid integers, booleans, ports, URLs, or transport names fail validation rather than falling back silently.

ENCRYPT=false preserves the existing unencrypted connection behavior. Set ENCRYPT=true for TLS. With encryption enabled, keep TRUST_SERVER_CERTIFICATE=false for certificates that chain to a trusted authority. Use TRUST_SERVER_CERTIFICATE=true only when explicitly accepting a self-signed or otherwise untrusted certificate, such as local development.

Multi-database behavior

DATABASES is an allowlist. Every tool accepts an optional databaseName. When a tool omits it, the server uses DATABASE_NAME if that name is allowed, otherwise it uses the first entry in DATABASES. A requested database outside the allowlist is rejected.

Safe writes and DDL

READONLY=true removes insert, update, delete, and DDL tools. Read-only preview tools remain available because they do not modify data.

When writes are enabled:

1. insert_data, update_data, delete_data, and DDL tools require confirmed: true unless the client completes MCP elicitation.
2. update_data and delete_data require nonempty structured filters, not raw SQL WHERE text.
3. With the default REQUIRE_WRITE_PREVIEW=true, call preview_update or preview_delete first and pass its previewToken to the matching write.
4. Preview tokens expire after 10 minutes, are single-use, and are bound to the same tool, table, filters, and update payload.
5. MAX_WRITE_ROWS rejects oversized operations, and update/delete execution applies a row cap.

Supported filter operators are =, !=, >, >=, <, <=, LIKE, IN, IS NULL, and IS NOT NULL.

DDL tools are registered when READONLY=false, but calls fail with DDL_DISABLED unless ENABLE_DDL=true.

For insert_data, pass the table in tableName and the schema separately in schemaName. Do not use a dotted schema.table value for tableName.

Streamable HTTP

The default transport is stdio. To run the stateless HTTP transport from a directory containing a configured .env:

MCP_TRANSPORT=http npx -y @eamonboyle/mssql-mcp

The default endpoint is:

http://127.0.0.1:3333/mcp

An HTTP client must accept application/json, text/event-stream. Each HTTP request creates a fresh MCP server instance. Preview tokens use a process-wide store so they remain valid across requests to the same process.

For a reverse proxy or externally published path, set MCP_BASE_URL to the public base without the final /mcp segment:

MCP_BASE_URL=https://example.com/services/mssql

The server continues binding to MCP_HTTP_HOST:MCP_HTTP_PORT, logs https://example.com/services/mssql/mcp as its public endpoint, and exposes that URL through mssql://config/server. MCP_E2E_BASE_URL is a separate test-harness variable used only by scripts/e2e-mcp-tools.mjs.

Cursor HTTP configuration:

{
  "mcpServers": {
    "mssql-http": {
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

Tools

| Tool | Mode | Purpose | | ------------------------ | ----- | ---------------------------------------------------------------- | | list_databases | Read | List configured databases | | list_table | Read | List tables, optionally filtered by schema names in parameters | | describe_table | Read | Describe a table schema | | list_objects | Read | List tables, views, procedures, functions, and triggers | | describe_object | Read | Return object metadata and definitions | | summarize_schema | Read | Summarize object counts by type and schema | | list_largest_tables | Read | Rank tables by storage and row count | | list_foreign_keys | Read | List foreign keys | | describe_relationships | Read | Describe foreign keys involving one table | | describe_dependencies | Read | List objects that depend on an object | | analyze_table | Read | Return row counts, storage, and index details | | read_data | Read | Execute a validated SELECT query | | search_data | Read | Search columns with parameterized LIKE predicates | | explain_query | Read | Generate an estimated SELECT execution plan | | preview_update | Read | Preview an update and issue a token when required | | preview_delete | Read | Preview a delete and issue a token when required | | insert_data | Write | Insert rows | | update_data | Write | Update rows selected by structured filters | | delete_data | Write | Delete rows selected by structured filters | | create_table | DDL | Create a table | | create_index | DDL | Create an index | | drop_table | DDL | Drop a table |

Resources and prompts

Clients with MCP resource support can discover:

• mssql://config/server
• mssql://config/prompts
• mssql://database/{databaseName}/tables
• mssql://database/{databaseName}/objects
• mssql://database/{databaseName}/schema-summary
• mssql://database/{databaseName}/foreign-keys
• mssql://table/{databaseName}/{schemaName}/{tableName}
• mssql://object/{databaseName}/{schemaName}/{objectName}
• mssql://database/{databaseName}/object/{schemaName}/{objectName}/dependencies
• mssql://query-plan/{planId}
• mssql://query-result/{resultId}

Table and object listings are cached for 30 seconds. Query plan and large query result resources are temporary process-local artifacts.

Available prompts:

• explore_schema
• draft_safe_select
• review_write_operation

Development

For local source development only:

git clone https://github.com/eamonboyle/mssql-mcp.git
cd mssql-mcp
npm install
npm run build
node /path/to/mssql-mcp/dist/index.js

The repository includes a seeded SQL Server 2022 Docker environment:

cp .env.example .env
npm run db:up
npm run test:e2e

See docs/dev-database.md for database and E2E details and CONTRIBUTING.md for build, lint, and test commands.

Troubleshooting

• SERVER_PORT must be a valid TCP port: use a whole number from 1 to 65535.
• getaddrinfo ENOTFOUND localhost,1434: move 1434 from SERVER_NAME to SERVER_PORT.
• DDL_DISABLED: set ENABLE_DDL to "true" only when DDL access is intended.
• PREVIEW_TOKEN_INVALID: create a new matching preview and use its token once within 10 minutes.
• stdio JSON parse errors: ensure scripts and dependencies write logs to stderr, not stdout.
• database rejected: add it to DATABASES and use the exact allowed name in databaseName.

Security

• Use a dedicated SQL login with the minimum permissions required.
• Set READONLY=true whenever writes are unnecessary.
• Keep ENABLE_DDL=false unless schema changes are explicitly needed.
• Keep credentials out of source control and use your client's secret-input support or a secrets manager.
• Bind HTTP mode to a trusted interface and add network authentication or isolation outside this package.
• Set ENCRYPT=true for TLS deployments and keep TRUST_SERVER_CERTIFICATE=false when the server certificate is publicly or privately trusted.
• Report vulnerabilities through the security policy.

Project links

• Changelog
• Contributing
• Code of Conduct
• Security Policy
• License