SQL Server MCP Client
About
A Microsoft SQL Server client implementing the Model Context Protocol (MCP). This server provides SQL query capabilities through a simple MCP interface.
Details
- License
- MIT
Explore
- JSON Schema Output: Parameter metadata compatible with validation tools
- Case-Insensitive Parameters: Flexible parameter naming with @ prefix normalization
- SQL Server Feature Detection: Comprehensive capability reporting
- Two-Mode Architecture: Optimized for both single-database and multi-database scenarios
- Configurable Timeouts: Default and per-operation timeout control with runtime management tools
- Background Session Management: Execute long-running queries and procedures with session-based monitoring
- Execution Timing: Automatic wall-clock and SQL Server-reported timing on query and stored procedure results
- Query Profiling: Optional per-table IO statistics and actual XML execution plans for performance analysis
- Rows Affected: Automatic reporting of rows affected by DML operations
Returns detailed information about the capabilities and features of the connected SQL Server instance.
Example request:
{
"name": "server_capabilities",
"parameters": {}
}
Example response in Server Mode:
{
"version": "Microsoft SQL Server 2019",
"majorVersion": 15,
"minorVersion": 0,
"buildNumber": 4123,
"edition": "Enterprise Edition",
"isAzureSqlDatabase": false,
"isAzureVmSqlServer": false,
"isOnPremisesSqlServer": true,
"toolMode": "server",
"features": {
"supportsPartitioning": true,
"supportsColumnstoreIndex": true,
"supportsJson": true,
"supportsInMemoryOLTP": true,
"supportsRowLevelSecurity": true,
"supportsDynamicDataMasking": true,
"supportsDataCompression": true,
"supportsDatabaseSnapshots": true,
"supportsQueryStore": true,
"supportsResumableIndexOperations": true,
"supportsGraphDatabase": true,
"supportsAlwaysEncrypted": true,
"supportsExactRowCount": true,
"supportsDetailedIndexMetadata": true,
"supportsTemporalTables": true
}
}
This tool is useful for:
- Determining which features are available in your SQL Server instance
- Debugging compatibility issues
- Understanding which query patterns will be used
- Verifying whether you're in server or database mode
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
SQL Server MCP ClientCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- .NET 10.0 SDK (for local development/deployment)
- Docker (for container deployment)
- Configurable tool enablement for security
- Environment-based configuration
- Comprehensive error handling with standardized error messages
- Input validation against SQL Server metadata
Integration tests verify the MCP server against a real SQL Server instance. The test framework automatically manages Docker containers: it finds a free port (in the 14330–14339 range), starts a SQL Server container with a unique name, runs all tests, and removes the container when done.
The only prerequisite is that Docker is running:
cd tst
dotnet test --filter "TestType=Integration"
The integration tests cover both database mode (connection string with Database=) and server mode (connection string without Database=), including tool metadata verification and functional tests for query execution, table listing, and schema retrieval.
Integration tests also run automatically in CI via the Integration Tests workflow, which can be triggered manually from the GitHub Actions tab.
With .NET 10 SDK, you can run the tool without installing it globally using dotnet tool exec:
dotnet tool exec -y ave.mcpserver.mssqlclient
The -y flag accepts prompts automatically. The tool is cached locally but not added to your PATH.
Add the server configuration to the mcpServers section in your configuration file.
By default, only read-only tools are enabled (listing tables, viewing schemas, listing stored procedures). To enable query and stored procedure execution, add the corresponding environment variables set to "true":
| Setting | Description | Default |
|---------|-------------|---------|
| DatabaseConfiguration__EnableExecuteQuery | Enable execute_query / execute_query_in_database tools | false |
| DatabaseConfiguration__EnableExecuteStoredProcedure | Enable execute_stored_procedure / execute_stored_procedure_in_database tools | false |
| DatabaseConfiguration__EnableStartQuery | Enable start_query / start_query_in_database session tools | false |
| DatabaseConfiguration__EnableStartStoredProcedure | Enable start_stored_procedure / start_stored_procedure_in_database session tools | false |
| DatabaseConfiguration__MaxCellOutputLength | Maximum characters displayed per cell in query results. Values longer than this are truncated with .... Set to 0 to disable truncation. | 40 |
Requires .NET 10 SDK. Install the tool once, then use it directly.
dotnet tool install --global Ave.McpServer.MsSqlClient
"mssql": {
"command": "ave-mcpserver-mssqlclient",
"env": {
"MSSQL_CONNECTIONSTRING": "Data Source=localhost;Integrated Security=True;MultipleActiveResultSets=True;TrustServerCertificate=True;",
"DatabaseConfiguration__EnableExecuteQuery": "true",
"DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
"DatabaseConfiguration__EnableStartQuery": "true",
"DatabaseConfiguration__EnableStartStoredProcedure": "true"
}
}
To update: dotnet tool update --global Ave.McpServer.MsSqlClient
The available tools differ depending on which mode the server is operating in, with some tools available in both modes:
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"sql server mcp client": {
"mssqlclient-mcp-server": {
"command": "docker",
"args": [
"pull",
"aadversteeg/mssqlclient-mcp-server:latest"
]
}
}
}
}McpServers
{
"mssqlclient-mcp-server": {
"command": "docker",
"args": [
"pull",
"aadversteeg/mssqlclient-mcp-server:latest"
]
}
}> Breaking Change in 0.0.5: Query and stored procedure execution tools are now disabled by default for security. If you were relying on the previous defaults, you must now explicitly enable them by setting the corresponding environment variables to "true":
> - DatabaseConfiguration__EnableExecuteQuery
> - DatabaseConfiguration__EnableExecuteStoredProcedure
> - DatabaseConfiguration__EnableStartQuery
> - DatabaseConfiguration__EnableStartStoredProcedure
>
> See Configuring Claude Desktop / Claude Code for examples.
A comprehensive Microsoft SQL Server client implementing the Model Context Protocol (MCP). This server provides extensive SQL Server capabilities including query execution, schema discovery, and stored procedure management through a simple MCP interface.
Overview
The SQL Server MCP client is built with .NET Core using the Model Context Protocol C# SDK (github.com/modelcontextprotocol/csharp-sdk). It provides tools for executing SQL queries, managing stored procedures, listing tables, and retrieving comprehensive schema information from SQL Server databases. The server is designed to be lightweight yet powerful, demonstrating how to create a robust MCP server with practical database functionality. It can be deployed either directly on a machine or as a Docker container.
The MCP client operates in one of two modes:
- Database Mode: When a specific database is specified in the connection string, only operations within that database context are available
- Server Mode: When no database is specified in the connection string, server-wide operations across all databases are available
Features
Core Database Operations
- Execute SQL queries on connected SQL Server databases - List all tables with schema and row count information - Retrieve detailed schema information for specific tables - Comprehensive stored procedure management and executionStored Procedure Support
- Parameter Discovery: Get detailed parameter information in table or JSON Schema format - Type-Safe Execution: Automatic JSON-to-SQL type conversion based on parameter metadata - Rich Metadata: Support for input/output parameters, default values, and data type constraints - Cross-Database Operations: Execute procedures across different databases (Server Mode)Advanced Features
- JSON Schema Output: Parameter metadata compatible with validation tools - Case-Insensitive Parameters: Flexible parameter naming with @ prefix normalization - SQL Server Feature Detection: Comprehensive capability reporting - Two-Mode Architecture: Optimized for both single-database and multi-database scenarios - Configurable Timeouts: Default and per-operation timeout control with runtime management tools - Background Session Management: Execute long-running queries and procedures with session-based monitoring - Execution Timing: Automatic wall-clock and SQL Server-reported timing on query and stored procedure results - Query Profiling: Optional per-table IO statistics and actual XML execution plans for performance analysis - Rows Affected: Automatic reporting of rows affected by DML operationsSecurity & Configuration
- Configurable tool enablement for security - Environment-based configuration - Comprehensive error handling with standardized error messages - Input validation against SQL Server metadataGetting Started
Prerequisites
- .NET 10.0 SDK (for local development/deployment)
- Docker (for container deployment)
Build Instructions (for development)
If you want to build the project from source:
1. Clone this repository:
git clone https://github.com/aadversteeg/mssqlclient-mcp-server.git
2. Navigate to the source directory:
cd mssqlclient-mcp-server/src
3. Build the project:
dotnet build
4. Run the unit tests:
dotnet test
Running Integration Tests
Integration tests verify the MCP server against a real SQL Server instance. The test framework automatically manages Docker containers: it finds a free port (in the 14330–14339 range), starts a SQL Server container with a unique name, runs all tests, and removes the container when done.
The only prerequisite is that Docker is running:
cd tst
dotnet test --filter "TestType=Integration"
The integration tests cover both database mode (connection string with Database=) and server mode (connection string without Database=), including tool metadata verification and functional tests for query execution, table listing, and schema retrieval.
Integration tests also run automatically in CI via the Integration Tests workflow, which can be triggered manually from the GitHub Actions tab.
Docker Support
Docker Hub
The SQL Server MCP Client is available on Docker Hub.
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
