SkillAgentSearch skills...

mcp-mssql

Read-only-by-default MCP server for one or many SQL Servers: schema discovery, SELECT-only queries, execution-plan analysis, opt-in writes.

Install / Use

claude mcp add alyiox -- npx -y github:alyiox/mcp-mssql

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

84/100

Supported Platforms

Claude Code
Claude Desktop

Our assessment of mcp-mssql

mcp-mssql scores 84/100 on our quality scale, 601st of 947 AI & Machine Learning skills we index.

Its MCP Server is 17 KB long, well organised into 20 sections with 12 code examples: a thorough specification that gives an agent plenty to work with.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 21 days ago, so mcp-mssql is actively maintained.
  • Our last check on 2026-11-10 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-09. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

mcp-mssql compared with similar skills

All 4 of these similar skills score higher than mcp-mssql; compare them before choosing.

SkillScoreStarsUpdatedFormat
mcp-mssql (this skill)by alyiox841021d agoMCP Server
claude-memby thedotmack100117.6ktodayCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md

Frequently asked questions

How do I install mcp-mssql?
Run claude mcp add alyiox -- npx -y github:alyiox/mcp-mssql. The install tabs above show the steps for each supported agent.
Which AI agents does mcp-mssql work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is mcp-mssql safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is mcp-mssql still maintained?
The repository was last updated 21 days ago, so mcp-mssql is actively maintained.

MCP SQL Server

<!-- mcp-name: io.github.alyiox/mcp-mssql -->

Build Status NuGet Version License: MIT

A read-only-by-default Model Context Protocol (MCP) server for Microsoft SQL Server that provides schema discovery, select-only queries, execution-plan analysis, opt-in writes, and profile-based access to multiple servers from a single toolset deployment.

Requirements: .NET 10.0 or later runtime, 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)
export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
npx -y @modelcontextprotocol/inspector@latest dotnet dnx Alyio.McpMssql --prerelease
# Option 2: Install and run as a global tool
dotnet tool install --global Alyio.McpMssql --prerelease
export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
npx -y @modelcontextprotocol/inspector@latest mcp-mssql
# Option 3: Run from source (clone repo, then)
export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"
npx -y @modelcontextprotocol/inspector@latest dotnet run --project src/Alyio.McpMssql -f net10.0

The Inspector connects in the legacy protocol era by default, where long-running calls never run as tasks. Set Protocol Era to auto or modern in Server Settings, or pass --protocol-era <auto|modern> on the command line. For example:

npx -y @modelcontextprotocol/inspector@latest --protocol-era auto dotnet run --project src/Alyio.McpMssql -f net10.0

Configuration

A profile is one SQL Server connection: a connection string, the row and timeout caps that apply to it, and whether writes are allowed. A profile named default always exists; every tool takes an optional profile to reach another, and list_profiles reports what is configured.

Settings come from three sources, merged field by field, later winning:

  1. the user-scoped appsettings.json — any number of profiles;
  2. McpMssql__Profiles__<NAME>__<FIELD> environment variables — any number of profiles;
  3. flat MCPMSSQL_<FIELD> environment variables — the default profile only.

Because the merge is per field rather than per profile, an appsettings.json can carry the full set while a flat MCPMSSQL_CONNECTION_STRING repoints the default profile at a local server, leaving its other fields intact. There is no fallback connection string: a profile without one — including a default that nothing configured — fails startup.

Each setting has one field name, spelled three ways — the JSON path under McpMssql:Profiles:<NAME>, that same path with : replaced by __ as an environment variable, or the flat form:

| Field | Flat variable | Default | Hard ceiling | |---|---|---|---| | ConnectionString | MCPMSSQL_CONNECTION_STRING | required | — | | Description | MCPMSSQL_DESCRIPTION | none | — | | AllowWrite | MCPMSSQL_ALLOW_WRITE | false | — | | Query:MaxRows | MCPMSSQL_QUERY_MAX_ROWS | 500 | 1 000 | | Query:CommandTimeoutSeconds | MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS | 30 | 300 | | Query:SnapshotMaxRows | MCPMSSQL_QUERY_SNAPSHOT_MAX_ROWS | 10 000 | 50 000 | | Query:SnapshotCommandTimeoutSeconds | MCPMSSQL_QUERY_SNAPSHOT_COMMAND_TIMEOUT_SECONDS | 120 | 300 | | Analyze:CommandTimeoutSeconds | MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS | 300 | 600 | | Write:CommandTimeoutSeconds | MCPMSSQL_WRITE_COMMAND_TIMEOUT_SECONDS | 60 | 600 |

Caps are per profile. A value above its ceiling — or below 1 — is clamped at startup and the adjustment is logged as a warning on stderr; a flat value that is not an integer, or not a boolean for AllowWrite, is ignored, leaving whatever the other sources set.

Single connection: flat environment variables are the shortest path.

# Connection string (required).
export MCPMSSQL_CONNECTION_STRING="Server=127.0.0.1;User ID=sa;Password=<YourStrong@Passw0rd>;Encrypt=True;TrustServerCertificate=True;"

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

# Optional caps, defaults shown.
export MCPMSSQL_QUERY_MAX_ROWS="500"
export MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS="30"
export MCPMSSQL_QUERY_SNAPSHOT_MAX_ROWS="10000"
export MCPMSSQL_QUERY_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"
export MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS="300"

# Optional write access, off by default; also controls whether run_command
# is advertised at all. A soft guard, not a database permission — prefer a
# db_datareader login for a hard read-only guarantee.
export MCPMSSQL_ALLOW_WRITE="false"
export MCPMSSQL_WRITE_COMMAND_TIMEOUT_SECONDS="60"

Multiple connections: use the user-scoped appsettings.json, which keeps credentials out of the host's process environment.

  • Unix-like: ~/.config/mcp-mssql/appsettings.json
  • Windows: %USERPROFILE%\.config\mcp-mssql\appsettings.json
{
  "McpMssql": {
    "Profiles": {
      "default": {
        "ConnectionString": "Server=...;User ID=...;Password=...;",
        "Description": "Primary connection",
        "Query": {
          "MaxRows": 500,
          "CommandTimeoutSeconds": 60,
          "SnapshotMaxRows": 10000,
          "SnapshotCommandTimeoutSeconds": 120
        },
        "Analyze": {
          "CommandTimeoutSeconds": 300
        }
      },
      "warehouse": {
        "ConnectionString": "Server=warehouse.example.com;...",
        "Description": "Warehouse read-only"
      },
      "migrations": {
        "ConnectionString": "Server=...;User ID=...;Password=...;",
        "Description": "Write-enabled profile for schema changes",
        "AllowWrite": true,
        "Write": {
          "CommandTimeoutSeconds": 60
        }
      }
    }
  }
}

Profile names are case-insensitive, and the structured environment form splits on __, so McpMssql__Profiles__WAREHOUSE__ConnectionString is profile warehouse, field ConnectionString. A missing appsettings.json is fine — the server starts on whatever sources remain — but one that is not valid JSON fails startup.

Local development: store the connection string in user-secrets, then run with DOTNET_ENVIRONMENT=Development so secrets and a working-directory appsettings.json load as extra sources.

dotnet user-secrets set "MCPMSSQL_CONNECTION_STRING" "..." --project src/Alyio.McpMssql
npx -y @modelcontextprotocol/inspector -e DOTNET_ENVIRONMENT=Development dotnet run --project src/Alyio.McpMssql

Connection string syntax: the usual Server=host,port;Database=db;User ID=...;Password=...;Encrypt=True; keywords of Microsoft.Data.SqlClient, which also supports Microsoft Entra (Azure AD) authentication: set Authentication 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 connection profiles. Call first when picking a non-default profile. Returns name, description and allow_write per profile. | — | | get_object | Get metadata for one relation (columns, indexes, constraints, relationships) or routine (definition). name accepts Users, dbo.Users or [dbo].[Users]. includes omitted → columns. Relations also carry an approximate row_count. | kind, name, profile, catalog, schema, includes | | run_query | Execute read-only T-SQL SELECT; only SELECT allowed (no DML/DDL). Returns results as CSV in the data field (inline) or a snapshot resource URI when snapshot=true. Inline limit: 500 rows (hard ceiling 1000). Snapshot limit: 10 000 rows (hard ceiling 50 000). Prefer analyze_query for plan tuning. | sql, profile, catalog, parameters, snapshot | | analyze_query | Analyze execution plan for a read-only SELECT. Returns compact JSON summary (cost, operators, cardinality, warnings, missing_indexes, waits, stats); no result rows, full XML at plan_uri. | sql, profile, catalog, parameters, estimated | | run_command | Execute write T-SQL (DDL/DML). Advertised only when some profile sets AllowWrite=true (off by default); still rejected at call time when the target profile is locked. Caller manages transactions. Returns rows_affected (−1 for DDL) and server messages. Marked destructive; intended for human-supervised use. | sql, profile, catalog, parameters |

  • kind — relation or routine.
  • includes — Array of detail sections: columns, indexes, constraints, relationships (relations only), definition (routines only). relationships returns foreign keys in both directions.

Catalog browsing is left to run_query over sys.objects, sys.schemas and sys.databases. get_object accepts analyze_query's missing_indexes[].table as-is.

Resources

| URI template | Description | |---|---| | mssql://profiles | List configured connection profiles, including allow_write. Same data as list_profiles. | | mssql://plans/{id} | Retrieve full XML execution plan by ID from analyze_query; entries expire after 7 days. | | mssql://snapshots/{id} | Retrieve full query result as CSV by ID from run_query (snapshot=true); entries expire after 7 days. |

Plans and snapshots are written to disk, under ~/.cache/mcp-mssql/plans/ and ~/.cache/mcp-mssql/snapshots/ (%USERPROFILE%\.cache\mcp-mssql\ on Windows). Expired files are swept the first time the server touches the store.

Long-running calls (MCP Tasks)

Snapshot queries (run_query with snapshot=true) and actual-plan analysis (analyze_query without estimated=true) run as tasks for clients that negotiate protocol 2026-07-28 and declare io.modelcontextprotocol/tasks on the request: the call returns a task handle at once and the client polls tasks/get (every 2 s suggested) for the usual result. Every other client, and every other call, gets the ordinary synchronous result. Tasks live in memory for an hour and end with the server process; tasks/cancel stops the running command.

Security

The query tools (run_query, analyze_query) are read-only (SELECT only) and use parameterized @paramName binding. Use environment variables, config file or user-secrets for connection strings—never commit secrets.

What counts as read-only. The SQL is parsed with ScriptDom and must be exactly one SELECT statement in a single batch — not merely text that begins with SELECT. Multi-statement and GO-separated scripts are rejected, and so are these, despite being syntactically SELECTs:

| Rejected | Reason | |---|---| | SELECT ... INTO | Materializes a new table. | | SELECT @v = ... | Assigns a variable, mutating session state. | | `NEXT VALUE FOR

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryAI
Updated21d ago
Forks1

Languages

C#

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info