Enables deployment of the MCP server using Docker containers, with configuration via environment variables and docker-compose for simplified setup and management.
Supports configuration through environment variables loaded from .env files, allowing customization of connection settings, security parameters, timeouts, and caching behavior.
Provides access to the repository for cloning and installation, with documentation and setup instructions accessible through GitHub.
Integrates structured logging through the pino logger, with configurable log levels for detailed application monitoring and troubleshooting.
Supports development using TypeScript, with type-safety and compilation features for robust server implementation and monitoring of code changes during development.
Provides an XML-based interface for submitting queries, executing stored procedures, and exploring database schemas when interacting with the MCP server.
MCP MSSQL Server
This is a Model Context Protocol (MCP) server for SQL Server interactions. It allows Large Language Models (LLMs) to execute SQL queries, run stored procedures, and explore database schemas with enhanced security and robustness.
Features
- Secure SQL Query Execution: Run - SELECTqueries against SQL Server databases. All queries are parsed and validated to ensure only- SELECTstatements are executed.
- Stored Procedure Support: Execute stored procedures with parameterized inputs. 
- Schema Exploration: View database table and column definitions, with results cached for performance. 
- Robust Connection Management: Utilizes a global connection pool for efficient reuse of database connections, with configurable retry logic and timeouts. 
- Enhanced Security: - SQL query parsing and - SELECT-only whitelist.
- SQL_ALLOWED_DATABASESenvironment variable to whitelist accessible databases.
- Protection against common SQL injection patterns for database context switching. 
- Blocks execution of potentially harmful system procedures or commands in direct queries. 
 
- Configurable Caching: Database schema information is cached with a configurable Time-To-Live (TTL). 
- Structured Logging: Integrated - pinologger for detailed and structured application logs.
- Docker Ready: Simple deployment with Docker. 
Quick Start
Using Docker (Recommended)
For complete Docker setup instructions, see the Docker README.
Configuration
The server is configured using environment variables. Create a .env file in the root directory (you can copy .env.example) to set these values.
For a detailed guide on all configuration options and how to set them up, please see CONFIG.
| Category | Variable | Description | Default (from config.js) | 
| Connection | 
 | SQL Server hostname or IP | 
 | 
| 
 | SQL Server port | 
 | |
| 
 | SQL Server username | 
 | |
| 
 | SQL Server password | Required | |
| 
 | Default database name to connect to | 
 | |
| Security | 
 | Enable encryption (set to 
 to disable) | 
 | 
| 
 | Trust server certificate (set to 
 to disable) | 
 | |
| 
 | Comma-separated list of databases the server is allowed to access. If empty, access is less restricted (relies on DB user permissions). | 
 (empty list) | |
| Timeouts & Retries | 
 | Connection timeout (ms) | 
 | 
| 
 | Request timeout for queries (ms) | 
 | |
| 
 | Max number of retries for initial connection attempts | 
 | |
| 
 | Initial delay (ms) before retrying a failed connection | 
 | |
| 
 | Maximum delay (ms) for connection retries (uses exponential backoff) | 
 | |
| Connection Pool | 
 | Max connections in pool | 
 | 
| 
 | Min connections in pool | 
 | |
| 
 | Idle timeout for connections in pool (ms) | 
 | |
| Caching | 
 | Time-To-Live for schema cache (ms) | 
 (5 minutes) | 
| MCP Server | 
 | Name of the MCP server | 
 | 
| 
 | Version of the MCP server | 
 | |
| Logging | 
 | Log level for pino logger (e.g., 
 , 
 , 
 , 
 , 
 , 
 , 
 ). This is read directly from 
 in 
 , not part of 
 . | 
 | 
Using with Claude
To add this MCP server to Claude CLI:
In the Claude conversation, you can:
- Execute - SELECTqueries:<mcp:execute_query database="YourDatabaseName"> SELECT TOP 10 * FROM YourTable </mcp:execute_query>- (The - databaseattribute is optional if operating on the default- SQL_DATABASEor if- SQL_ALLOWED_DATABASESimplies a single choice.)
- Execute stored procedures: <mcp:execute_StoredProcedure database="YourDatabaseName"> { "procedure": "YourSchema.YourProcedureName", "parameters": [ {"name": "Param1", "type": "NVarChar", "value": "SomeValue"}, {"name": "Param2", "type": "Int", "value": 123} ] } </mcp:execute_StoredProcedure>
- Explore database schema: <mcp:schema> YourDatabaseName </mcp:schema>- (If - YourDatabaseNameis omitted, it defaults to the- SQL_DATABASEspecified in the environment variables.)
Connection Handling
This MCP server utilizes a global, robust connection pool (mssql library's built-in pooling) managed by the DatabaseService.
- Efficiency: Connections are reused, reducing the overhead of establishing a new connection for each request. 
- Resilience: Implements retry logic with exponential backoff for initial connection establishment. 
- No Session State Across Calls: Unlike a session-per-user model, this server does not guarantee that subsequent MCP calls (e.g., two separate - execute_querycalls) from the LLM will use the exact same underlying database connection. Therefore, session-specific state like temporary tables or session variables created in one call may not be available in another. Each call should be considered atomic from a session state perspective. The- USE [database]command is issued within each operation if the target database differs from the pool's default, ensuring context for that specific operation.
Development
Local Development Setup
Security Notes
- SELECT: The server strictly enforces that only- SELECTqueries can be run via the- execute_querytool, using SQL parsing. DML (INSERT, UPDATE, DELETE) and DDL statements are blocked.
- Stored Procedure Execution: While stored procedures can perform any action their permissions allow, their execution is managed separately. 
- Database Whitelisting: Use the - SQL_ALLOWED_DATABASESenvironment variable to restrict which databases the server can interact with. For a detailed explanation of this feature and how it interacts with- SQL_DATABASE, please see- DATABASE_WHITELISTING.md.
- System Procedure Blocking: Direct execution of common system procedures (e.g., - sp_,- xp_) and commands like- RECONFIGUREor- WAITFOR DELAYvia- execute_queryis blocked. Stored procedures should be used for legitimate system interactions.
- Input Validation: Database names for context switching and stored procedure names undergo format validation. SQL parsing provides an additional layer of validation for queries. 
- Parameterized Inputs: Stored procedure parameters are handled by the - mssqllibrary, which typically parameterizes them to prevent SQL injection.
Troubleshooting
If you encounter issues:
- Check container logs: - docker logs mssql-mcp(if using Docker).
- Check the server's console output for pino logs if running locally. 
- Verify all required environment variables in your - .envfile are correctly set, especially- SQL_PASSWORD,- SQL_SERVER,- SQL_USER, and- SQL_DATABASE.
- Ensure the database(s) you are trying to access are listed in - SQL_ALLOWED_DATABASESif you have set this variable.
- Confirm network connectivity to your SQL Server instance from where the MCP server is running. 
- The test scripts ( - test-mcp.sh,- test-session-persistence.sh) might need review/updates.
For detailed Docker troubleshooting, see the Docker README.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that allows Large Language Models like Claude to execute SQL queries, explore database schemas, and maintain persistent connections to SQL Server databases.
Related MCP Servers
- -security-license-qualityA Model Context Protocol server that enables Large Language Models to access and interact with database connections, including viewing schemas and performing CRUD operations on connected databases.Last updated -
- Asecurity-licenseAqualityA Model Context Protocol server that enables executing SQL queries and managing connections with Microsoft SQL Server databases.Last updated -1546MIT License
- -security-license-qualityA Model Context Protocol server that enables large language models like Claude to perform comprehensive interactions with Firebase Firestore databases, supporting full CRUD operations, complex queries, and advanced features like transactions and TTL management.Last updated -34MIT License
- -security-license-qualityA Model Context Protocol server that enables LLMs like Claude to interact with SQLite and SQL Server databases, allowing for schema inspection and SQL query execution.Last updated -3,221204MIT License