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

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.

SQL_AUTH_TYPE	What it does	Required vars (besides server/database)
sql	Classic SQL login (original behavior)	SQL_USER, SQL_PASSWORD
azure-default	Entra ID via DefaultAzureCredential (az login / env / workload / managed identity)	— (optional SQL_AZURE_CLIENT_ID for a user-assigned identity)
azure-service-principal	Entra app registration	SQL_AZURE_TENANT_ID, SQL_AZURE_CLIENT_ID, SQL_AZURE_CLIENT_SECRET
azure-password	Entra username + password (non-MFA only)	SQL_USER, SQL_PASSWORD, SQL_AZURE_CLIENT_ID, SQL_AZURE_TENANT_ID
azure-access-token	Pre-fetched Entra access token	SQL_ACCESS_TOKEN
azure-msi	Azure Managed Identity	— (optional SQL_AZURE_CLIENT_ID for a user-assigned identity)

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

Variable	Default	Description
READONLY	required	true = read-only (SELECT/WITH); false also registers write tools
SQL_PORT	1433	Server port
SQL_ENCRYPT	true	Encrypt connection (required for Azure SQL)
SQL_TRUST_CERT	false	Trust self-signed certs (dev only)
QUERY_TIMEOUT	30000	Query timeout ms (max 120000)
MAX_ROWS	1000	Max rows returned (max 5000)
POOL_MIN / POOL_MAX	2 / 10	Connection pool bounds
LOG_LEVEL	info	debug | info | warn | error

Available Tools

Query

Tool	Description
sql_execute	Execute SELECT/WITH queries with parameterized inputs

Schema

Tool	Description
schema_list_tables	List tables and views
schema_describe_table	Columns, indexes, foreign keys for a table
schema_list_columns	Search columns across tables
schema_list_procedures	List stored procedures
schema_list_indexes	List indexes with usage stats

Monitor

Tool	Description
monitor_active_queries	Currently running queries
monitor_blocking	Blocking sessions and lock chains
monitor_wait_stats	Wait statistics
monitor_database_size	Size and file usage
monitor_connections	Active connections
monitor_performance_counters	Performance counters

Analysis

Tool	Description
analyze_query	Execution plan and statistics
analyze_suggest_indexes	Suggested missing indexes
analyze_unused_indexes	Unused indexes
analyze_duplicate_indexes	Duplicate/overlapping indexes
analyze_fragmentation	Index fragmentation
analyze_statistics	Stale statistics

Write (only when READONLY=false)

Tool	Description
sql_insert	Insert a row
sql_update	Update rows (WHERE required)
sql_delete	Delete rows (WHERE required)

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.