MCP SQL Server Tool

A read-only Model Context Protocol (MCP) server for Microsoft SQL Server that supports metadata discovery, parameterized queries, and query analysis, with profile-based configuration and strict no-DML/DDL enforcement.

Requirements: .NET 10.0 SDK, SQL Server, and a connection string.

Quick start

Set MCPMSSQL_CONNECTION_STRING and run the server in one of these ways:

# Option 1: Run from NuGet package (e.g. with MCP Inspector)
npx -y @modelcontextprotocol/inspector \
  -e MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;" \
  dotnet dnx Alyio.McpMssql --prerelease

# Option 2: Install and run as a global tool
dotnet tool install --global Alyio.McpMssql --prerelease
npx -y @modelcontextprotocol/inspector -e MCPMSSQL_CONNECTION_STRING="..." mcp-mssql

# Option 3: Run from source (clone repo, then)
npx -y @modelcontextprotocol/inspector -e MCPMSSQL_CONNECTION_STRING="..." dotnet run --project src/Alyio.McpMssql

Use --prerelease for pre-release builds. When using the package: entrypoint dotnet dnx Alyio.McpMssql; when installed as a tool: command mcp-mssql.

Configuration

All settings use the MCPMSSQL prefix: flat environment variables (e.g. MCPMSSQL_CONNECTION_STRING) for a single connection, or hierarchical env vars (e.g. MCPMSSQL__PROFILES__DEFAULT__CONNECTIONSTRING) for profile-based config. The same structure under key MCPMSSQL is also supported in a user-scoped appsettings.json file:

• Unix-like: ~/.config/mcpmssql/appsettings.json
• Windows: %USERPROFILE%\.config\mcpmssql\appsettings.json

Configuration precedence is:

1. appsettings.json
2. appsettings.{Environment}.json
3. user-scoped appsettings.json
4. user-secrets in Development
5. hierarchical environment variables such as MCPMSSQL__PROFILES__DEFAULT__CONNECTIONSTRING
6. flat legacy environment variables such as MCPMSSQL_CONNECTION_STRING for the default profile

Single server / one connection: Set the following as environment variables.

# Connection string (required).
export MCPMSSQL_CONNECTION_STRING="Server=...;User ID=...;Password=...;"

# Optional description for the default profile (tooling/AI discovery).
export MCPMSSQL_DESCRIPTION="Primary connection"

# Optional max rows per query (default `5000`).
export MCPMSSQL_QUERY_MAX_ROWS="5000"

# Optional query timeout in seconds (default `30`).
export MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS="60"

# Optional analyze timeout in seconds (default `300`).
export MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS="300"

Multiple servers or connections: Use environment variables or the same structure in the user-scoped appsettings.json file.

• Use environment variables with the MCPMSSQL prefix, then __ for each level (e.g. MCPMSSQL__PROFILES__DEFAULT__CONNECTIONSTRING).
• For each profile, set MCPMSSQL__PROFILES__<name>__CONNECTIONSTRING, and optionally add __DESCRIPTION and __QUERY.
• The default profile is the one named default. Define it with MCPMSSQL__PROFILES__DEFAULT__... or use the single-connection variables (MCPMSSQL_CONNECTION_STRING, etc.) to create or override the default profile when set.

Example (environment variables):

# Default profile
export MCPMSSQL__PROFILES__DEFAULT__CONNECTIONSTRING="Server=...;User ID=...;Password=...;"
export MCPMSSQL__PROFILES__DEFAULT__DESCRIPTION="Primary connection"
export MCPMSSQL__PROFILES__DEFAULT__QUERY__MAXROWS="5000"
export MCPMSSQL__PROFILES__DEFAULT__QUERY__COMMANDTIMEOUTSECONDS="60"
export MCPMSSQL__PROFILES__DEFAULT__ANALYZE__COMMANDTIMEOUTSECONDS="300"

# Named profile
export MCPMSSQL__PROFILES__WAREHOUSE__CONNECTIONSTRING="Server=warehouse.example.com;..."
export MCPMSSQL__PROFILES__WAREHOUSE__QUERY__MAXROWS="10000"
export MCPMSSQL__PROFILES__WAREHOUSE__QUERY__COMMANDTIMEOUTSECONDS="120"
export MCPMSSQL__PROFILES__WAREHOUSE__ANALYZE__COMMANDTIMEOUTSECONDS="600"

# Single-connection (flat) keys create or override the default profile:
export MCPMSSQL_CONNECTION_STRING="Server=...;User ID=...;Password=...;"
export MCPMSSQL_DESCRIPTION="Primary connection"
export MCPMSSQL_QUERY_MAX_ROWS="5000"
export MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS="60"
export MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS="300"

Example (user-scoped appsettings.json):

{
  "McpMssql": {
    "Profiles": {
      "default": {
        "ConnectionString": "Server=...;User ID=...;Password=...;",
        "Description": "Primary connection",
        "Query": {
          "MaxRows": 5000,
          "CommandTimeoutSeconds": 60
        },
        "Analyze": {
          "CommandTimeoutSeconds": 300
        }
      },
      "warehouse": {
        "ConnectionString": "Server=warehouse.example.com;...",
        "Description": "Warehouse read-only"
      }
    }
  }
}

Local development: Set the connection string, then run with that environment:

• Store connection string in user-secrets (Development only).

dotnet user-secrets set "MCPMSSQL_CONNECTION_STRING" "..." --project src/Alyio.McpMssql

• Run server with MCP inspector (use DOTNET_ENVIRONMENT=Development so user-secrets load).

npx -y @modelcontextprotocol/inspector -e DOTNET_ENVIRONMENT=Development dotnet run --project src/Alyio.McpMssql

Azure SQL / Microsoft Entra ID: This MCP server uses Microsoft.Data.SqlClient, which supports Microsoft Entra (Azure AD) authentication. Set the Authentication property in the connection string to a supported mode (e.g. Active Directory Default, Active Directory Managed Identity, or Active Directory Interactive) when connecting to Azure SQL. See Connect to Azure SQL with Microsoft Entra authentication and SqlClient for all modes and details.

Tools and resources

All tools accept an optional profile; when omitted, the default profile is used.

Tools

Tool	Description	Key params
list_profiles	List configured profiles.	—
get_server_properties	Get server properties and execution limits.	profile
list_objects	List catalog metadata (catalogs, schemas, relations, routines).	kind, profile, catalog, schema
get_object	Get metadata for one relation or routine (columns, indexes, constraints, definition).	kind, name, profile, catalog, schema, includes
run_query	Execute read-only T-SQL SELECT.	sql, profile, catalog, parameters
analyze_query	Analyze execution plan for a read-only SELECT. Returns a compact JSON summary of cost, top operators, cardinality issues, warnings, missing indexes, wait stats, and statistics. Full XML plan available via the returned plan_uri.	sql, profile, catalog, parameters, estimated

• kind — catalog, schema, relation, or routine. For get_object, only relation or routine.
• includes — Array of detail sections: columns, indexes, constraints (relation only), definition (routine only).

Resources

URI template	Description
mssql://profiles	List configured profiles.
mssql://server-properties?{profile}	Get server properties and execution limits.
mssql://objects?{kind,profile,catalog,schema}	List catalog metadata.
mssql://objects/{kind}/{name}{?profile,catalog,schema,includes}	Get metadata for one relation or routine.
mssql://plans/{id}	Retrieve full XML execution plan by ID (returned by analyze_query).

Resources mirror their corresponding tools and return JSON (except mssql://plans/{id} which returns XML).

Security

Read-only (SELECT only); parameterized @paramName. Use environment variables or user-secrets for connection strings—never commit secrets.

MCP host examples

Snippets for common MCP clients. Copy one and replace the connection string; ensure dotnet is on your PATH.

Note: For security, store connection strings in environment variables or a secret manager (for example, user-secrets in development) instead of directly in config files.

Cursor / Gemini

{
  "mcpServers": {
    "mssql": {
      "command": "dotnet",
      "args": ["dnx", "Alyio.McpMssql", "--prerelease", "--yes"],
      "env": {
        "MCPMSSQL_CONNECTION_STRING": "Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Codex

[mcp_servers.mssql]
command = "dotnet"
args = ["dnx", "Alyio.McpMssql", "--prerelease", "--yes"]
[mcp_servers.mssql.env]
MCPMSSQL_CONNECTION_STRING = "Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"

Open Code

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mssql": {
      "type": "local",
      "enabled": true,
      "command": ["dotnet", "dnx", "Alyio.McpMssql", "--prerelease", "--yes"],
      "environment": {
        "MCPMSSQL_CONNECTION_STRING": "Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

GitHub Copilot

{
  "inputs": [],
  "servers": {
    "mssql": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["dnx", "Alyio.McpMssql", "--prerelease", "--yes"],
      "env": {
        "MCPMSSQL_CONNECTION_STRING": "Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
      }
    }
  }
}

Config file locations: Cursor .cursor/mcp.json, Codex/Copilot/OpenCode vary by client; see your client’s MCP docs.

Integration tests

Tests use a real SQL Server and the default profile (MCPMSSQL_CONNECTION_STRING from environment variables or user-secrets). The suite expects a database named McpMssqlTest: the connection string must include Initial Catalog=McpMssqlTest. The test infrastructure creates, seeds, and drops this database. Set the secret for the test project:

dotnet user-secrets set "MCPMSSQL_CONNECTION_STRING" \
  "Server=localhost,1433;User ID=sa;Password=...;TrustServerCertificate=True;Encrypt=True;Initial Catalog=McpMssqlTest;" \
  --project test/Alyio.McpMssql.Tests

Why this instead of Data API Builder?

Data API Builder (DAB) is a full REST/GraphQL API with CRUD and auth. This project is a small, read-only MCP server for agents: stdio, parameterized SELECT only, minimal surface. Choose this for agent workflows and low operational overhead; choose DAB for CRUD, REST/GraphQL, and rich policies.

Contributing

Open issues or PRs; follow existing style and add tests where appropriate.

License

MIT. See LICENSE.