sql-assistant-mcp

A Model Context Protocol (MCP) server for SQL Server / Azure SQL — query, monitor, and analyze databases directly from Claude. It is the data plane for the sql-assistant-agent lineage / reconciliation copilot.

Fork notice. Derived from @fabriciofs/mcp-sql-server (MIT). The headline addition is Microsoft Entra ID authentication; all original tools are retained. See LICENSE for attribution.

Features

• Query Execution — SELECT/WITH queries with parameterized inputs (read-only enforced)

• Schema Exploration — tables, columns, procedures, indexes

• Database Monitoring — active queries, blocking, wait stats, connections, sizes

• Performance Analysis — missing/unused/duplicate indexes, fragmentation, statistics

• Microsoft Entra ID auth — az login, service principal, managed identity, access token, or Entra password

• Write Operations — INSERT/UPDATE/DELETE, registered only when READONLY=false

Related MCP server: MCP SQL Server

Installation

This server is run from a local build (not published to npm).

git clone <your-repo-url> sql-assistant-mcp
cd sql-assistant-mcp
npm install        # runs the build via the prepare script
npm run build      # (re)compile to build/

Authentication modes

Set SQL_AUTH_TYPE (default sql). SQL_SERVER + SQL_DATABASE are always required.

The Entra modes acquire tokens through @azure/identity. Azure SQL requires encryption — keep SQL_ENCRYPT=true. A SQL_CONNECTION_URL is shorthand for sql auth.

Local-dev example (recommended): az login

{
  "mcpServers": {
    "dash2": {
      "command": "node",
      "args": ["/abs/path/to/sql-assistant-mcp/build/index.js"],
      "env": {
        "SQL_SERVER": "your-server.database.windows.net",
        "SQL_DATABASE": "Dash2",
        "SQL_AUTH_TYPE": "azure-default",
        "SQL_ENCRYPT": "true",
        "READONLY": "true"
      }
    }
  }
}

Run az login once (granting your Entra user access to the DB); the server picks up the credential automatically.

Service-principal example

{
  "env": {
    "SQL_SERVER": "your-server.database.windows.net",
    "SQL_DATABASE": "Dash2",
    "SQL_AUTH_TYPE": "azure-service-principal",
    "SQL_AZURE_TENANT_ID": "<tenant-guid>",
    "SQL_AZURE_CLIENT_ID": "<app-guid>",
    "SQL_AZURE_CLIENT_SECRET": "<secret>",
    "READONLY": "true"
  }
}

SQL login (original behavior)

{
  "env": {
    "SQL_SERVER": "localhost",
    "SQL_DATABASE": "mydb",
    "SQL_USER": "sa",
    "SQL_PASSWORD": "yourpassword",
    "READONLY": "true"
  }
}

See .env.example for the full variable reference.

Other settings

Available Tools

Query

Schema

Monitor

Analysis

Write (only when READONLY=false)

Security Considerations

• Keep READONLY=true unless writes are explicitly required — the read-only validator blocks anything that isn't a SELECT/WITH, plus stacked-query and SELECT INTO bypasses.

• Prefer Entra ID auth over SQL logins; avoid embedding secrets where you can use azure-default / managed identity.

• Grant the principal minimal permissions (read-only DB role for this copilot).

Requirements

• Node.js >= 20

• SQL Server 2016+ or Azure SQL Database / Managed Instance

Development

npm install        # install + build
npm run build      # compile
npm run dev        # watch compile
npm run typecheck  # tsc --noEmit
npm test           # vitest
npm run inspector  # MCP Inspector

License

MIT — see LICENSE. Original work © fabriciofs; modifications © Benrishty.