[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_126":127},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","alyiox","moduleId","mcp-mssql","@alyiox/mcp-mssql","displayName","Microsoft SQL Server","tagline","Read-only MCP for Microsoft SQL Server: metadata discovery, parameterized SELECT, plans.","iconKey","https://avatars.githubusercontent.com/u/7823985?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783337902000,"updatedAt",1788237126000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.alyiox%2Fmcp-mssql","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",7,"upstreamUpdatedAt",1788233931000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/alyiox/mcp-mssql","githubRepoFullName","alyiox/mcp-mssql","releaseId","ext-alyiox-mcp-mssql","version","1.3.0","descriptionMarkdown","# MCP SQL Server Tool\n\n\n\n[![Build Status](https://github.com/alyiox/mcp-mssql/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alyiox/mcp-mssql/actions/workflows/ci.yml)\n[![NuGet Version](https://img.shields.io/nuget/v/Alyio.McpMssql.svg)](https://www.nuget.org/packages/Alyio.McpMssql)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nA read-only-by-default [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Microsoft SQL Server. Beyond schema discovery and parameterized SELECT queries, it exposes **execution-plan analysis**: `analyze_query` returns cost, operators, cardinality estimates, warnings, and index suggestions, so an agent can work out *why* a query is slow instead of only running it. Profile-based configuration serves multiple connections from a single server.\n\nThe query tools enforce SELECT-only (no DML/DDL); an optional `run_command` tool can execute arbitrary write T-SQL, but only on profiles that explicitly opt in via `AllowWrite` (locked off by default).\n\n**Requirements:** .NET 8.0 or later runtime (the tool targets `net8.0` and `net10.0`), SQL Server, and a connection string. Building from source requires the .NET 10.0 SDK.\n\n## Quick start\n\nSet `MCPMSSQL_CONNECTION_STRING` and run the server in one of these ways:\n\n```bash\n# Option 1: Run from NuGet package (e.g. with MCP Inspector)\nexport MCPMSSQL_CONNECTION_STRING=\"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\nnpx -y @modelcontextprotocol/inspector dotnet dnx Alyio.McpMssql --prerelease\n```\n\n```bash\n# Option 2: Install and run as a global tool\ndotnet tool install --global Alyio.McpMssql --prerelease\nexport MCPMSSQL_CONNECTION_STRING=\"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\nnpx -y @modelcontextprotocol/inspector mcp-mssql\n```\n\n```bash\n# Option 3: Run from source (clone repo, then)\nexport MCPMSSQL_CONNECTION_STRING=\"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\nnpx -y @modelcontextprotocol/inspector dotnet run --project src/Alyio.McpMssql\n```\n\nUse `--prerelease` for pre-release builds.\n\n## Configuration\n\nAll settings use the **MCPMSSQL** prefix. **Flat** environment variables (e.g. `MCPMSSQL_CONNECTION_STRING`) are the straightforward way to configure the **default** profile when you have a single connection. For multiple profiles, the user-scoped `appsettings.json` file is recommended.\n\n**Single connection:** Configure via environment variables.\n\n```bash\n# Connection string (required).\nexport MCPMSSQL_CONNECTION_STRING=\"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n\n# Optional description for the default profile (tooling/AI discovery).\nexport MCPMSSQL_DESCRIPTION=\"Primary connection\"\n\n# Optional max rows per interactive query (default `500`; hard ceiling `1000`).\nexport MCPMSSQL_QUERY_MAX_ROWS=\"500\"\n\n# Optional query timeout in seconds (default `30`).\nexport MCPMSSQL_QUERY_COMMAND_TIMEOUT_SECONDS=\"60\"\n\n# Optional max rows for snapshot queries (default `10000`; hard ceiling `50000`).\nexport MCPMSSQL_QUERY_SNAPSHOT_MAX_ROWS=\"10000\"\n\n# Optional snapshot query timeout in seconds (default `120`).\nexport MCPMSSQL_QUERY_SNAPSHOT_COMMAND_TIMEOUT_SECONDS=\"120\"\n\n# Optional analyze timeout in seconds (default `300`).\nexport MCPMSSQL_ANALYZE_COMMAND_TIMEOUT_SECONDS=\"300\"\n\n# Optional: enable write commands (DDL/DML) via run_command (default `false`).\n# Soft guard only — prefer a db_datareader login for a hard read-only guarantee.\nexport MCPMSSQL_ALLOW_WRITE=\"false\"\n\n# Optional write command timeout in seconds (default `60`; hard ceiling `600`).\nexport MCPMSSQL_WRITE_COMMAND_TIMEOUT_SECONDS=\"60\"\n```\n\n**Multiple connections:** Use the user-scoped `appsettings.json` file (recommended). Env vars also work via .NET host conventions (`MCPMSSQL__PROFILES____CONNECTIONSTRING`, etc.).\n\n- Unix-like: `~/.config/mcp-mssql/appsettings.json`\n- Windows: `%USERPROFILE%\\.config\\mcp-mssql\\appsettings.json`\n\nExample (`appsettings.json`):\n\n```json\n{\n \"McpMssql\": {\n \"Profiles\": {\n \"default\": {\n \"ConnectionString\": \"Server=...;User ID=...;Password=...;\",\n \"Description\": \"Primary connection\",\n \"Query\": {\n \"MaxRows\": 500,\n \"CommandTimeoutSeconds\": 60,\n \"SnapshotMaxRows\": 10000,\n \"SnapshotCommandTimeoutSeconds\": 120\n },\n \"Analyze\": {\n \"CommandTimeoutSeconds\": 300\n }\n },\n \"warehouse\": {\n \"ConnectionString\": \"Server=warehouse.example.com;...\",\n \"Description\": \"Warehouse read-only\"\n },\n \"migrations\": {\n \"ConnectionString\": \"Server=...;User ID=...;Password=...;\",\n \"Description\": \"Write-enabled profile for schema changes\",\n \"AllowWrite\": true,\n \"Write\": {\n \"CommandTimeoutSeconds\": 60\n }\n }\n }\n }\n}\n```\n\n**Local development:** Store the connection string in user-secrets, then run with `DOTNET_ENVIRONMENT=Development` so secrets load.\n\n```bash\ndotnet user-secrets set \"MCPMSSQL_CONNECTION_STRING\" \"...\" --project src/Alyio.McpMssql\nnpx -y @modelcontextprotocol/inspector -e DOTNET_ENVIRONMENT=Development dotnet run --project src/Alyio.McpMssql\n```\n\n**Azure SQL / Microsoft Entra ID:** This MCP server uses [Microsoft.Data.SqlClient](https://www.nuget.org/packages/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](https://learn.microsoft.com/en-us/sql/connect/ado-net/sql/azure-active-directory-authentication) for all modes and details.\n\n## Tools and resources\n\nAll tools accept an optional `profile`; when omitted, the default profile is used.\n\n**Tools**\n\n| Tool | Description | Key params |\n|---|---|---|\n| **`list_profiles`** | List configured connection profiles. Call first when picking a non-default profile. | — |\n| **`get_server_properties`** | Get server properties and execution limits (timeouts, row caps, guardrails). | `profile` |\n| **`list_objects`** | List catalog metadata. `kind=catalog`: databases; `schema`: schemas; `relation`: tables/views; `routine`: procedures/functions. `catalog` omitted → active catalog (ignored for `kind=catalog`). `schema` omission depends on kind. | `kind`, `profile`, `catalog`, `schema` |\n| **`get_object`** | Get metadata for one relation or routine. Use `list_objects` to resolve names. Returns empty detail payloads if `includes` is null. | `kind`, `name`, `profile`, `catalog`, `schema`, `includes` |\n| **`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. Prefer `analyze_query` for plan tuning. | `sql`, `profile`, `catalog`, `parameters`, `snapshot` |\n| **`analyze_query`** | Analyze execution plan for a read-only SELECT. Returns compact JSON summary (cost, operators, cardinality, warnings, indexes, waits, stats). Fetch full XML from `plan_uri`; does not return result rows. | `sql`, `profile`, `catalog`, `parameters`, `estimated` |\n| **`run_command`** | Execute write T-SQL (DDL/DML). Rejected unless the target `profile` sets `AllowWrite=true` (off by default). Caller manages transactions. Returns `rows_affected` (−1 for DDL) and server `messages`. Marked destructive; intended for human-supervised use. | `sql`, `profile`, `catalog`, `parameters` |\n\n- **`kind`** — `catalog`, `schema`, `relation`, or `routine`. For `get_object`, only `relation` or `routine`.\n- **`includes`** — Array of detail sections: `columns`, `indexes`, `constraints` (relations only), `definition` (routines only).\n\n**Resources**\n\n| URI template | Description |\n|---|---|\n| `mssql://profiles` | List configured connection profiles. Same data as `list_profiles`. |\n| `mssql://server-properties?{profile}` | Get server properties and execution limits. Same data as `get_server_properties`. |\n| `mssql://objects?{kind,profile,catalog,schema}` | List catalog metadata. Schema omission behavior matches `list_objects`. |\n| `mssql://objects/{kind}/{name}{?profile,catalog,schema,includes}` | Get metadata for one relation or routine. `includes` is required. |\n| `mssql://plans/{id}` | Retrieve full XML execution plan by ID from `analyze_query`; entries expire after 7 days. |\n| `mssql://snapshots/{id}` | Retrieve full query result as CSV by ID from `run_query` (snapshot=true); entries expire after 1 day. |\n\nResources mirror their corresponding tools and return JSON (except `mssql://plans/{id}` which returns XML and `mssql://snapshots/{id}` which returns CSV).\n\n## Security\n\nThe query tools (`run_query`, `analyze_query`) are read-only (`SELECT` only) and use parameterized `@paramName` binding. Use environment variables or user-secrets for connection strings—never commit secrets.\n\n**Writes are opt-in.** The `run_command` tool executes arbitrary T-SQL. It is rejected unless the target profile sets `AllowWrite=true`, which defaults to `false`, so existing deployments stay read-only with no change. The tool is always advertised and rejects at call time on locked profiles.\n\n`AllowWrite` is a soft, application-level guard, **not** a security boundary — it constrains this server, not the database. For a genuine read-only guarantee, connect with a login restricted to `db_datareader`, and keep write-enabled profiles pointed at credentials scoped to only what they need. `run_command` is marked `destructive` via MCP tool annotations so hosts can gate it behind confirmation, but honor those annotations at the host's discretion.\n\n## MCP host examples\n\nSnippets for common MCP clients. Replace the connection string with your own; ensure `dotnet` is on your PATH. The `env` block is not required if the connection string is already set via `appsettings.json` or environment variables.\n\n### Cursor\n\n```json\n{\n \"mcpServers\": {\n \"mssql\": {\n \"command\": \"dotnet\",\n \"args\": [\"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"],\n \"env\": {\n \"MCPMSSQL_CONNECTION_STRING\": \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n }\n }\n }\n}\n```\n\n### Gemini\n\n```json\n{\n \"mcpServers\": {\n \"mssql\": {\n \"command\": \"dotnet\",\n \"args\": [\"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"],\n \"env\": {\n \"MCPMSSQL_CONNECTION_STRING\": \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n }\n }\n }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.mssql]\ncommand = \"dotnet\"\nargs = [\"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"]\n[mcp_servers.mssql.env]\nMCPMSSQL_CONNECTION_STRING = \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n```\n\n### Open Code\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"mssql\": {\n \"type\": \"local\",\n \"enabled\": true,\n \"command\": [\"dotnet\", \"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"],\n \"environment\": {\n \"MCPMSSQL_CONNECTION_STRING\": \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n }\n }\n }\n}\n```\n\n### Claude Code\n\n```json\n{\n \"mcpServers\": {\n \"mssql\": {\n \"command\": \"dotnet\",\n \"args\": [\"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"],\n \"env\": {\n \"MCPMSSQL_CONNECTION_STRING\": \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n }\n }\n }\n}\n```\n\n### GitHub Copilot\n\n```json\n{\n \"inputs\": [],\n \"servers\": {\n \"mssql\": {\n \"type\": \"stdio\",\n \"command\": \"dotnet\",\n \"args\": [\"dnx\", \"Alyio.McpMssql\", \"--prerelease\", \"--yes\"],\n \"env\": {\n \"MCPMSSQL_CONNECTION_STRING\": \"Server=127.0.0.1;User ID=sa;Password=;Encrypt=True;TrustServerCertificate=True;\"\n }\n }\n }\n}\n```\n\n\n## Integration tests\n\nTests 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:\n\n```bash\ndotnet user-secrets set \"MCPMSSQL_CONNECTION_STRING\" \\\n \"Server=localhost,1433;User ID=sa;Password=...;TrustServerCertificate=True;Encrypt=True;Initial Catalog=McpMssqlTest;\" \\\n --project test/Alyio.McpMssql.Tests\n```\n\n**One framework at a time.** The single `McpMssqlTest` database is shared by every test, and the fixtures drop and recreate it on initialization. Within one test process this is safe — the `SqlServer` collection disables parallelization. Across processes it is not: the test project targets both `net8.0` and `net10.0`, and `dotnet test` runs the two framework modules in parallel, so they race on that one database. There is no cross-process locking, so run a single framework at a time:\n\n```bash\ndotnet test --framework net8.0\ndotnet test --framework net10.0\n```\n\nCI does the same, iterating over `TARGET_FRAMEWORKS` sequentially.\n\n## Why this instead of Data API Builder?\n\nData 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.\n\n## Roadmap\n\n**MCP Tasks extension ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)).** Snapshot queries and execution-plan analysis run under long timeouts (120 s and 300 s by default), which is the shape the [Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview) exists for: the server returns a durable task handle instead of blocking, and the client polls `tasks/get` until the work reaches a terminal state.\n\nThe fit is good; adoption is the blocker. Tasks is an opt-in extension (`io.modelcontextprotocol/tasks`) that a server may only use when the client declares support in its per-request capabilities, and no client currently lists it in the [extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). Deferred until clients ship support.\n\n## Contributing\n\nOpen issues or PRs; follow existing style and add tests where appropriate.\n\n## License\n\nMIT. See [LICENSE](https://github.com/alyiox/mcp-mssql/blob/main/LICENSE).\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_108":109,"_110":111,"_112":113,"_114":115,"_116":66,"_117":118},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ai-agents","azure-ad","azure-sql","csharp","database","dotnet","execution-plan","llm","mssql","nuget","query-optimization","read-only","sql","sql-server","topics",[94,95,96,97,98,99,100,101,123,124,125,102,103,104,105,106,107],"license","MIT","language","C#","registryName","io.github.alyiox/mcp-mssql","homepage","packages",[119],{"_120":103,"_121":122,"_71":72},"registryType","identifier","Alyio.McpMssql","mcp","mcp-server","model-context-protocol","ENV",{"_128":129,"_130":131,"_132":133},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]