About this project

This is a read-only-by-default Model Context Protocol (MCP) server for Microsoft SQL Server, distributed as a .NET NuGet package (Alyio.McpMssql) targeting .NET 8.0 and 10.0. It is designed to let AI agents and developers safely interact with SQL Server instances with minimal operational overhead. Core capabilities include catalog metadata discovery (listing databases, schemas, tables, views, stored procedures and functions), execution of safe parameterized SELECT-only queries with configurable row limits and timeouts, and execution plan analysis for slow query diagnosis. The analyze_query tool returns compact JSON summaries of execution plans including cost, operator details, cardinality estimates, warnings, index suggestions, and wait stats, with full XML plans available via a dedicated resource URI that expires after 7 days. Configuration supports both single-connection setups via MCPMSSQL_ prefixed environment variables, and multi-profile setups via user-scoped appsettings.json files (located at ~/.config/mcp-mssql/appsettings.json on Unix-like systems, %USERPROFILE%\.config\mcp-mssql\appsettings.json on Windows). Per-profile settings include connection strings, query row caps, timeout values, and optional write access. It natively supports Azure SQL with Microsoft Entra authentication via Microsoft.Data.SqlClient. The server exposes a set of MCP tools: list_profiles to enumerate configured connections, get_server_properties to retrieve server limits and properties, list_objects and get_object for metadata discovery, run_query for SELECT-only query execution (with support for inline results up to 1000 rows or snapshot CSV results up to 50000 rows, with snapshots expiring after 1 day), analyze_query for execution plan analysis, and run_command for executing DDL/DML write operations. The run_command tool is disabled by default, only enabled on profiles that explicitly set AllowWrite=true, and is marked as destructive for host-side confirmation gating. Security defaults to read-only: write access is explicitly opt-in per profile, and queries use parameterized @paramName binding to prevent injection. The AllowWrite flag is an application-level guard, not a database security boundary; for a hard read-only guarantee, the documentation recommends using a login restricted to the db_datareader role. It can be deployed in three ways: run directly from the NuGet package, install as a global .NET tool, or run from source. Configuration snippets are provided for common MCP hosts including Cursor, Gemini, Codex, Open Code, Claude Code, and GitHub Copilot. Integration tests require a real SQL Server instance with a McpMssqlTest database, with guidance to run test frameworks sequentially to avoid cross-process database race conditions. The project roadmap includes planned support for the MCP Tasks extension (SEP-2663) to handle long-running queries via durable task handles instead of blocking, pending client adoption of the extension. The project is licensed under MIT.