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-mssqlIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mcp-mssql (this skill)by alyiox | 84 | 10 | 21d ago | MCP Server |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.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.
Skill content
View source on GitHubMCP SQL Server
<!-- mcp-name: io.github.alyiox/mcp-mssql -->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:
- the user-scoped
appsettings.json— any number of profiles; McpMssql__Profiles__<NAME>__<FIELD>environment variables — any number of profiles;- flat
MCPMSSQL_<FIELD>environment variables — thedefaultprofile 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—relationorroutine.includes— Array of detail sections:columns,indexes,constraints,relationships(relations only),definition(routines only).relationshipsreturns 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
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
