# Mssqlclient Mcp Server

> A Microsoft SQL Server client implementing the Model Context Protocol (MCP). This server provides SQL query capabilities through a simple MCP interface.

- **Type:** MCP server
- **Install:** `agentstack add mcp-aadversteeg-mssqlclient-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aadversteeg](https://agentstack.voostack.com/s/aadversteeg)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aadversteeg](https://github.com/aadversteeg)
- **Source:** https://github.com/aadversteeg/mssqlclient-mcp-server

## Install

```sh
agentstack add mcp-aadversteeg-mssqlclient-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SQL Server MCP Client

> **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](#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](https://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 execution

### Stored 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 operations

### Security & Configuration
- Configurable tool enablement for security
- Environment-based configuration
- Comprehensive error handling with standardized error messages
- Input validation against SQL Server metadata

## Getting 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:
   ```bash
   git clone https://github.com/aadversteeg/mssqlclient-mcp-server.git
   ```

2. Navigate to the source directory:
   ```bash
   cd mssqlclient-mcp-server/src
   ```

3. Build the project:
   ```bash
   dotnet build
   ```

4. Run the unit tests:
   ```bash
   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:

```bash
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
# Pull the latest version
docker pull aadversteeg/mssqlclient-mcp-server:latest
```

### Manual Docker Build

If you need to build the Docker image yourself:

```bash
# Navigate to the repository root
cd mssqlclient-mcp-server

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t mssqlclient-mcp-server:latest src/

# Run the locally built image
docker run -d --name mssql-mcp -e "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;" mssqlclient-mcp-server:latest
```

### Local Registry Push

To push to your local registry:

```bash
# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t localhost:5000/mssqlclient-mcp-server:latest src/

# Push to local registry
docker push localhost:5000/mssqlclient-mcp-server:latest
```

#### Using Local Registry

If you have pushed the image to local registry running on port 5000, you can pull from it:

```bash
# Pull from local registry
docker pull localhost:5000/mssqlclient-mcp-server:latest
```

## .NET Tool

The SQL Server MCP Client is available as a .NET global tool on NuGet.

### Installation

```bash
dotnet tool install --global Ave.McpServer.MsSqlClient
```

### Running

```bash
ave-mcpserver-mssqlclient
```

### One-shot execution (without permanent installation)

With .NET 10 SDK, you can run the tool without installing it globally using `dotnet tool exec`:

```bash
dotnet tool exec -y ave.mcpserver.mssqlclient
```

The `-y` flag accepts prompts automatically. The tool is cached locally but not added to your PATH.

### Configuring Claude Desktop / Claude Code

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` |

#### Using .NET Tool

Requires .NET 10 SDK. This approach automatically downloads the tool on first use and updates to the latest version on subsequent runs.

```json
"mssql": {
  "command": "dotnet",
  "args": [
    "tool",
    "exec",
    "-y",
    "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"
  }
}
```

#### Using Global Installation

Requires .NET 10 SDK. Install the tool once, then use it directly.

```bash
dotnet tool install --global Ave.McpServer.MsSqlClient
```

```json
"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`

## MCP Protocol Usage

### Client Integration

To connect to the SQL Server MCP Client from your applications:

1. Use the Model Context Protocol C# SDK or any MCP-compatible client
2. Configure your client to connect to the server's endpoint
3. Call the available tools described below

### Available Tools

The available tools differ depending on which mode the server is operating in, with some tools available in both modes:

## Common Tools (Available in Both Modes)

#### server_capabilities

Returns detailed information about the capabilities and features of the connected SQL Server instance.

Example request:
```json
{
  "name": "server_capabilities",
  "parameters": {}
}
```

Example response in Server Mode:
```json
{
  "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

#### get_command_timeout

Returns current timeout configuration settings.

Example request:
```json
{
  "name": "get_command_timeout",
  "parameters": {}
}
```

Example response:
```json
{
  "defaultCommandTimeoutSeconds": 30,
  "connectionTimeoutSeconds": 15,
  "maxConcurrentSessions": 10,
  "sessionCleanupIntervalMinutes": 60,
  "totalToolCallTimeoutSeconds": 120,
  "timestamp": "2024-12-19 10:30:45 UTC"
}
```

#### set_command_timeout

Updates the default command timeout for all new operations.

**Note:** When `TotalToolCallTimeoutSeconds` is configured, the effective timeout will be the minimum of this value and the remaining total timeout. This ensures operations complete within the total tool call timeout limit.

Parameters:
- `timeoutSeconds` (required): New timeout in seconds (1-3600)

Example request:
```json
{
  "name": "set_command_timeout",
  "parameters": {
    "timeoutSeconds": 120
  }
}
```

Example response:
```json
{
  "message": "Default command timeout updated successfully",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "This change only affects new operations. Existing sessions will continue with their original timeout settings.",
  "timestamp": "2024-12-19 10:31:00 UTC"
}
```

#### Session Management Tools

These tools allow management of long-running queries and stored procedures through background sessions. They are particularly useful when operations would exceed the `TotalToolCallTimeoutSeconds` limit or when you need to run multiple operations concurrently.

##### get_session_status

Check the status of a running query or stored procedure session.

Parameters:
- `sessionId` (required): The session ID to check

Example request:
```json
{
  "name": "get_session_status",
  "parameters": {
    "sessionId": 12345
  }
}
```

Example response:
```json
{
  "sessionId": 12345,
  "type": "query",
  "query": "SELECT * FROM LargeTable",
  "databaseName": "Northwind",
  "startTime": "2024-12-19 10:30:00 UTC",
  "endTime": "2024-12-19 10:35:23 UTC",
  "duration": "323.5 seconds",
  "status": "completed",
  "isRunning": false,
  "rowCount": 1500000,
  "error": null,
  "timeoutSeconds": 600,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "LargeTable", "logicalReads": 45230, "physicalReads": 120, "readAheadReads": 44800 }
  ],
  "executionPlanXml": null
}
```

The following fields are included when available (null otherwise):

- `serverElapsedTimeMs` / `serverCpuTimeMs`: SQL Server-side timing (always captured)
- `rowsAffected`: Total rows affected by DML operations (always captured)
- `ioStats`: Per-table IO statistics (only when `includeIoStats` was `true` on the start tool)
- `executionPlanXml`: Actual XML execution plan (only when `includeExecutionPlan` was `true` on the start tool)

##### get_session_results

Get results from a completed or running query/stored procedure session.

Parameters:
- `sessionId` (required): The session ID to get results from
- `maxRows` (optional): Maximum number of rows to return

Example request:
```json
{
  "name": "get_session_results",
  "parameters": {
    "sessionId": 12345,
    "maxRows": 100
  }
}
```

Example response:
```json
{
  "sessionId": 12345,
  "type": "query",
  "status": "completed",
  "rowCount": 1500000,
  "results": "| CustomerID | CompanyName | ContactName |\n| ---------- | ----------- | ----------- |\n| ALFKI | Alfreds Futterkiste | Maria Anders |\n...\n... (showing first 100 rows of 1500000 total)",
  "maxRowsApplied": 100,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "Customers", "logicalReads": 42, "physicalReads": 0, "readAheadReads": 0 }
  ],
  "executionPlanXml": null
}
```

##### stop_session

Stop a running query or stored procedure session.

Parameters:
- `sessionId` (required): The session ID to stop

Example request:
```json
{
  "name": "stop_session",
  "parameters": {
    "sessionId": 12345
  }
}
```

Example response:
```json
{
  "sessionId": 12345,
  "status": "cancelled",
  "message": "Session cancelled successfully",
  "timestamp": "2024-12-19 10:32:15 UTC"
}
```

##### list_sessions

List all query and stored procedure sessions.

Parameters:
- `status` (optional): Filter by status - "all" (default), "running", or "completed"

Example request:
```json
{
  "name": "list_sessions",
  "parameters": {
    "status": "running"
  }
}
```

Example response:
```json
{
  "filter": "running",
  "totalSessions": 2,
  "sessions": [
    {
      "sessionId": 12345,
      "type": "query",
      "query": "SELECT * FROM LargeTable...",
      "databaseName": "Northwind",
      "startTime": "2024-12-19 10:30:00 UTC",
      "duration": "45.2 seconds",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    },
    {
      "sessionId": 12346,
      "type": "storedprocedure",
      "query": "GenerateMonthlyReport",
      "databaseName": "Sale

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aadversteeg](https://github.com/aadversteeg)
- **Source:** [aadversteeg/mssqlclient-mcp-server](https://github.com/aadversteeg/mssqlclient-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aadversteeg-mssqlclient-mcp-server
- Seller: https://agentstack.voostack.com/s/aadversteeg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.