Skip to main content
Glama
sql-server-mcp

sql-server-mcp

by ahaugerud

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 session

  • An 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

MCP_SQL_SERVER_NAME

yes

SQL Server / Fabric SQL endpoint hostname, e.g. xyz-xyz.datawarehouse.fabric.microsoft.com

MCP_SQL_DATABASE_NAME

yes

Default database to connect to

MCP_AZURE_TENANT_ID

yes, unless using SQL login

The Entra ID tenant ID — pins auth to this directory even if your machine has other az login sessions active

MCP_SQL_USERNAME

no

SQL login username. If set, the server uses username + password authentication instead of Entra ID (and MCP_AZURE_TENANT_ID is not needed)

MCP_SQL_PASSWORD

with username

SQL login password. Must be set together with MCP_SQL_USERNAME

MCP_SQL_TRUST_SERVER_CERTIFICATE

no

Set to true to skip server certificate validation (needed for servers with self-signed or otherwise untrusted certificates, e.g. older on-prem SQL Server). Default: false

MCP_SQL_LEGACY_TLS

no

Set to true for old SQL Server hosts (e.g. SQL Server 2012) that reset the connection during the TLS handshake (TCP Provider: Error code 0x2746). Lowers OpenSSL's security level to 0 for this process (and its child processes), so it requires SQL login and is best avoided elsewhere. Default: false

MCP_MAX_ROWS

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-mcp

To run from a local checkout instead (e.g. during development), point --from at the path:

uvx --from /path/to/sql-server-mcp sql-server-mcp

On 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-only SELECT. Table references must be fully qualified as database.schema.table; there's no mutable "active database". Returns at most MCP_MAX_ROWS rows, 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 via INFORMATION_SCHEMA across one or more databases (all of them if databases is omitted).

  • export_query(sql, path, format?) — run a single read-only SELECT and 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 database

Available Tools

4 tools
export_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

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Read-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Microsoft SQL Server that lets LLMs explore schema and execute read-only SELECT queries, with optional stored procedure execution when explicitly enabled.
      3
      132 npm
      MIT