sql-server-mcp
This server lets you explore and export data from a read-only SQL Server / MS Fabric tenant using natural-language-driven MCP tool calls.
Run read-only queries —
query(sql)executes a singleSELECTand returns up to 25 rows as a Markdown table; tables must be fully qualified asdatabase.schema.table.Discover databases —
list_databases()lists user databases with status/metadata (max 25 rows).Search metadata —
search_schema(target, name, databases?, schema?, use_wildcard?)finds tables or columns viaINFORMATION_SCHEMA, across one, several, or all databases, with optional wildcard matching.Export full results —
export_query(sql, path, format?)runs aSELECTand writes the uncapped result to a local file (Parquet by default, or CSV per the schema; the README also mentions Excel/xlsx) for use in pandas, DuckDB, etc.Work across tenants — one process per Entra ID tenant, authenticated as you (Azure CLI or interactive browser login) or via SQL username/password, with optional cert-trust and legacy-TLS flags for older servers.
Control output size — cap rows per call with
MCP_MAX_ROWS(default 25).No local DB driver install needed —
mssql-pythonbundles its own driver, and it runs directly viauvx sql-server-mcp.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sql-server-mcp show me the top 10 rows from sales.dbo.orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sql-server-mcp
A local MCP server for read-only SQL Server / MS Fabric queries. Runs as a single-user process over stdio, authenticated as you (delegated Entra ID identity, not a service principal) — one server process per tenant.
Prerequisites
Python 3.14+ and uv
Either the Azure CLI logged in to the target tenant (
az login --tenant <tenant-id>), or just a browser available — the server falls back to an interactive browser login if there's no CLI sessionAn Entra ID account in the target tenant with read access to the target database (e.g.
db_datareader)
Related MCP server: powerbi-mcp-proxy
Configuration
Each tenant gets its own set of environment variables:
Variable | Required | Description |
| yes | SQL Server / Fabric SQL endpoint hostname, e.g. |
| yes | Default database to connect to |
| yes, unless using SQL login | The Entra ID tenant ID — pins auth to this directory even if your machine has other |
| no | SQL login username. If set, the server uses username + password authentication instead of Entra ID (and |
| with username | SQL login password. Must be set together with |
| no | Set to |
| no | Set to |
| no | Max rows returned per tool call (default: 25) |
Running it
The server is a uvx-runnable console script (sql-server-mcp), no
manual install step needed - uvx builds an isolated environment for it
on first run and reuses it afterwards:
uvx sql-server-mcpTo run from a local checkout instead (e.g. during development), point
--from at the path:
uvx --from /path/to/sql-server-mcp sql-server-mcpOn startup it acquires a token (via az login if available, otherwise an
interactive browser prompt) and runs over stdio. Database connectivity uses
mssql-python, which bundles
its own driver — no separate ODBC driver install is required.
Example MCP client config
One block per tenant:
{
"mcpServers": {
"tenant-a-sql": {
"command": "uvx",
"args": ["sql-server-mcp"],
"env": {
"MCP_SQL_SERVER_NAME": "tenant-a.datawarehouse.fabric.microsoft.com",
"MCP_SQL_DATABASE_NAME": "wh_silver",
"MCP_AZURE_TENANT_ID": "<tenant-a-tenant-id>"
}
},
"tenant-b-sql": {
"command": "uvx",
"args": ["sql-server-mcp"],
"env": {
"MCP_SQL_SERVER_NAME": "tenant-b.datawarehouse.fabric.microsoft.com",
"MCP_SQL_DATABASE_NAME": "wh_gold",
"MCP_AZURE_TENANT_ID": "<tenant-b-tenant-id>"
}
}
}
}Tools
query(sql)— run a single read-onlySELECT. Table references must be fully qualified asdatabase.schema.table; there's no mutable "active database". Returns at mostMCP_MAX_ROWSrows, as a Markdown table.list_databases()— list user databases with status/metadata.search_schema(target, name, databases?, schema?, use_wildcard?)— search table or column metadata viaINFORMATION_SCHEMAacross one or more databases (all of them ifdatabasesis omitted).export_query(sql, path, format?)— run a single read-onlySELECTand write the full, uncapped result to a local Parquet, CSV or Excel (xlsx, max 1,048,575 rows) file instead of returning it. For large results or when the output feeds into other local tools (pandas, DuckDB, etc.).
Development
uv run pytest # unit tests, no network/DB/Azure required
uv run python scripts/manual_smoke_test.py # real end-to-end check against a live databaseAvailable Tools
4 toolsexport_queryA
Execute a single read-only SELECT statement and write the full, uncapped result to a local Parquet or CSV file instead of returning it. Use this instead of query for large results or when the output will be processed by other local tools.
Inputs: sql (required), path (required), format. Returns: result
list_databasesA
List all user databases with status and metadata. Returns at most 25 rows.
Inputs: no named parameters. Returns: result
queryA
Execute a single read-only SELECT statement. Returns at most 25 rows. Table references must be fully qualified as database.schema.table - there is no mutable 'active database'.
Inputs: sql (required). Returns: result
search_schemaB
Search table or column metadata across databases via INFORMATION_SCHEMA. Omit databases to search every database on the server. Returns at most 25 rows.
Inputs: name (required), target (required), schema, databases, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: `query` for capped inline SELECTs, `export_query` for uncapped file output, `list_databases` for database enumeration, and `search_schema` for metadata lookup. The `query` vs `export_query` overlap is explicitly resolved by the description telling agents to prefer `export_query` for large results.
Three tools follow a clear verb_noun pattern (`list_databases`, `search_schema`, `export_query`), while `query` is a bare verb/noun that slightly breaks the pattern. The deviation is minor and still readable in context.
Four tools is well-scoped for a read-only SQL server interface, with each tool covering a distinct essential workflow: querying, exporting, listing databases, and searching schema metadata. Nothing feels redundant or missing at the count level.
The surface covers core read-only workflows well, including capped queries, large exports, database listing, and schema discovery via INFORMATION_SCHEMA. Minor gaps exist around dedicated table listing or describe-table convenience tools, but `search_schema` provides a workable path for those needs.
Related MCP Connectors
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceRead-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server that proxies MCP clients to Power BI, using your own Entra tenant and Azure subscription. It enables DAX queries, workspace listing, and dataset management while preserving user-specific row-level security.2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for safely exposing SQL Server database capabilities to LLM clients, with read-only mode, security features, and observability.29MIT
- AlicenseAqualityBmaintenanceMCP server for Microsoft SQL Server that lets LLMs explore schema and execute read-only SELECT queries, with optional stored procedure execution when explicitly enabled.3132 npmMIT