Skip to main content
Glama

SqlAugur

NuGet NuGet Downloads License: MIT .NET 10.0

An MCP server that gives AI assistants safe, read-only access to SQL Server databases. Every query is parsed into a full AST using Microsoft's official T-SQL parser — not regex — so comment injection, string literal tricks, and encoding bypasses are blocked at the syntax level.

┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
│              │  stdio   │  SqlAugur                                 │        │              │
│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
                          │  │  Validator │  │  DBA Services        │ │
                          │  └────────────┘  └──────────────────────┘ │
                          │  ┌────────────────────────────────────┐   │
                          │  │  Rate Limiter                      │   │
                          │  └────────────────────────────────────┘   │
                          └───────────────────────────────────────────┘

Quick Start

Use this order for all install methods:

  1. Install SqlAugur

  2. Save appsettings.json in the correct location

  3. Add SqlAugur to your MCP client config

  4. Verify by asking your assistant to call list_servers

Start with Installation for exact commands and file paths.

Related MCP server: mcp-sqlserver-readonly

Why This Approach

  • AST-level query validation — Most MCP database servers use keyword blocking or no validation at all. This project parses every query into a full syntax tree using Microsoft's official TSql180Parser. Comment injection, string literal tricks, and encoding bypasses are blocked at the syntax level, not with fragile regex patterns.

  • Rate limiting — Token bucket throughput limiting and concurrency control prevent runaway AI query loops from overwhelming production SQL Servers. No other MCP database server offers this.

  • DBA diagnostic tooling — Integrated support for First Responder Kit, DarlingData, and sp_WhoIsActive with parameter blocking that prevents write operations. This is an entirely new MCP capability category.

  • Response size optimisation — DBA tools exclude verbose columns (XML query plans, deadlock graphs, metric breakdowns) and truncate long strings by default, reducing response sizes by 90–99%. Use verbose and includeQueryPlans parameters to get full untruncated output when needed.

  • Progressive discovery — Up to 31 tools organized into toolsets that load on demand. Only 6 core tools are exposed initially, keeping the AI's context window small and reducing token usage. Additional toolsets are discovered and enabled as needed.

Features

Security

  • Read-only by design — only SELECT and CTE queries are permitted

  • AST-based query validation using ScriptDom (not regex)

  • Parameter blocking on all diagnostic stored procedures to prevent writes

  • Concurrency and throughput rate limiting

Database Tooling

  • Multi-server support — named connections to multiple SQL Server instances

  • Schema overview — concise Markdown schema maps with PKs, FKs, constraints, and defaults

  • Table documentation — Markdown descriptions of columns, indexes, foreign keys, and constraints

  • ER diagram generation — PlantUML and Mermaid diagrams with smart cardinality detection

  • Schema exploration — list programmable objects, view definitions, extended properties, dependency graphs

  • Query plan analysis — estimated or actual XML execution plans

  • DBA diagnostics — optional integration with First Responder Kit, DarlingData, and sp_WhoIsActive with automatic response size optimisation

  • Progressive discovery — dynamic toolset mode reduces initial context window usage by exposing tools on demand

Installation

All methods produce the same MCP server. Follow this order: install, save config, wire client, verify.

1. Install (prerequisite: .NET 10.0 runtime)

dotnet tool install -g SqlAugur

2. Save config file

# Linux/macOS
mkdir -p ~/.config/sqlaugur
# Edit ~/.config/sqlaugur/appsettings.json with your server connections

# Windows (PowerShell)
mkdir "$env:APPDATA\sqlaugur" -Force
# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections

Example appsettings.json to save at that location:

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    }
  }
}

3. Add to MCP client

{
  "mcpServers": {
    "sqlaugur": {
      "command": "sqlaugur"
    }
  }
}

To update: dotnet tool update -g SqlAugur

Docker / Podman

1. Run SqlAugur container

# Volume-mount a config file
docker run -i --rm \
  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
  ghcr.io/mbentham/sqlaugur:latest

# Or use environment variables (no config file needed)
docker run -i --rm \
  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
  ghcr.io/mbentham/sqlaugur:latest

Note: To reach a SQL Server on the host machine, use host.docker.internal (Docker Desktop) or --network=host (Linux). Replace docker with podman — all commands are identical. The :Z flag on volume mounts is required for SELinux-enabled systems (Fedora, RHEL); Docker Desktop users on macOS/Windows can omit it.

If you mount a config file, save it as /path/to/appsettings.json and mount it to /app/appsettings.json.

2. Add to MCP client

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
        "ghcr.io/mbentham/sqlaugur:latest"]
    }
  }
}
services:
  sqlaugur:
    image: ghcr.io/mbentham/sqlaugur:latest
    stdin_open: true
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro,Z

MCP client configuration:

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
    }
  }
}

Build from Source

1. Build (prerequisite: .NET 10.0 SDK)

git clone git@github.com:mbentham/SqlAugur.git
cd SqlAugur
dotnet publish SqlAugur -c Release -o SqlAugur/publish

2. Save config file

# Linux/macOS
cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
# Edit SqlAugur/publish/appsettings.json with your server connections

# Windows (PowerShell)
Copy-Item SqlAugur\appsettings.example.json SqlAugur\publish\appsettings.json
# Edit SqlAugur\publish\appsettings.json with your server connections

3. Add to MCP client

{
  "mcpServers": {
    "sqlaugur": {
      "command": "dotnet",
      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
    }
  }
}

Verify the MCP connection (LLM-first)

After restarting your MCP client, ask the assistant:

  • Call list_servers

  • Call list_databases for server "production"

Expected result:

  • list_servers returns your configured server name (for example production)

  • list_databases returns a JSON array of databases, not a connection or authentication error

If verification fails:

  1. Confirm MCP config runs the expected command (sqlaugur, docker run ..., or dotnet /path/to/SqlAugur.dll)

  2. Confirm appsettings.json is saved where your install method expects it:

    • Local tool: ~/.config/sqlaugur/appsettings.json (Linux/macOS) or %APPDATA%\sqlaugur\appsettings.json (Windows)

    • Container: mounted to /app/appsettings.json

    • Source build: next to the published DLL (SqlAugur/publish/appsettings.json)

  3. Confirm the tool call uses a configured server key (for example production)

  4. Confirm SQL connectivity and authentication in the connection string

Configuration

The server loads configuration from multiple sources. Higher-priority sources override lower ones:

  1. Command-line arguments

  2. Environment variables — using __ as section delimiter (e.g., SqlAugur__Servers__production__ConnectionString=...)

  3. Current working directory — appsettings.json in the directory you run the command from

  4. User config directory — ~/.config/sqlaugur/appsettings.json on Linux, %APPDATA%\sqlaugur\appsettings.json on Windows

  5. Azure Key Vault — when AzureKeyVaultUri is set (see below)

  6. App directory — appsettings.json next to the DLL

Example configuration (Windows Authentication — recommended):

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    },
    "MaxRows": 1000,
    "CommandTimeoutSeconds": 30,
    "MaxConcurrentQueries": 5,
    "MaxQueriesPerMinute": 60,
    "EnableFirstResponderKit": false,
    "EnableDarlingData": false,
    "EnableWhoIsActive": false,
    "EnableDynamicToolsets": false
  }
}

Option

Default

Description

Servers

—

Named SQL Server connections (name → connection string). Connections identify themselves to SQL Server as SqlAugur (program_name, Extended Events client_app_name) unless the connection string sets its own Application Name.

MaxRows

1000

Maximum rows returned per query, inline or in a result file

ResultFileThresholdRows

500

read_data results over this many rows (or about 40,000 characters) are written to a CSV file instead of returned inline, avoiding oversized stdio messages. 0 disables.

ResultsDirectory

sqlaugur/results under the user's local application data folder (%LOCALAPPDATA%\sqlaugur\results on Windows)

Where result files are written. Must be an absolute path.

ResultFileRetentionDays

7

Result files older than this are deleted at startup

CommandTimeoutSeconds

30

SQL command timeout for all queries and procedures

MaxConcurrentQueries

5

Maximum number of SQL queries that can execute concurrently

MaxQueriesPerMinute

60

Maximum queries allowed per minute (token bucket rate limit)

EnableFirstResponderKit

false

Enable First Responder Kit diagnostic tools (sp_Blitz, sp_BlitzFirst, sp_BlitzCache, sp_BlitzIndex, sp_BlitzWho, sp_BlitzLock, sp_BlitzPlanCompare)

EnableDarlingData

false

Enable DarlingData diagnostic tools (sp_PressureDetector, sp_QuickieStore, sp_QuickieCache, sp_HealthParser, sp_LogHunter, sp_HumanEventsBlockViewer, sp_IndexCleanup, sp_QueryReproBuilder)

EnableWhoIsActive

false

Enable sp_WhoIsActive session monitoring

EnableDynamicToolsets

false

Enable progressive tool discovery — DBA tools load on demand via 3 meta-tools instead of at startup. Reduces initial context window usage. The Enable* flags still control which toolsets are allowed.

AzureKeyVaultUri

—

Azure Key Vault URI (e.g., https://myvault.vault.azure.net/). When set, secrets from the vault are added as a configuration source using DefaultAzureCredential. Key Vault secret names use -- as a section separator (e.g., a secret named SqlAugur--Servers--prod--ConnectionString maps to SqlAugur:Servers:prod:ConnectionString).

Security Note: appsettings.json is gitignored to prevent accidental credential commits. See SECURITY.md for recommended authentication methods including Windows Authentication, Azure Managed Identity, and secure credential storage options.

Tools

The server provides 31 tools organized into toolsets. Six core tools are always available. Additional toolsets are loaded at startup (static mode) or on demand (dynamic mode).

Core Tools

Tool

Description

list_servers

Lists available SQL Server instances configured in appsettings.json.

list_databases

Lists all databases on a named server with names, IDs, states, and creation dates.

read_data

Executes a read-only SQL SELECT query. Only SELECT and WITH (CTE) queries are allowed. Small results are returned as JSON; large ones go to a CSV file, returning its path, row count, columns and a 10-row preview. Pass toFile: true to always get a file.

get_query_plan

Returns the estimated or actual XML execution plan for a SELECT query.

get_schema_overview

Concise Markdown schema overview: tables, columns, PKs, FKs, unique/check constraints, defaults. Supports compact mode, schema and table filtering.

describe_table

Comprehensive table metadata in Markdown: columns, data types, nullability, defaults, identity, computed expressions, indexes, FKs, constraints.

Tool

Description

list_programmable_objects

Lists views, stored procedures, functions, and triggers. Filterable by type and schema.

get_object_definition

Returns the source definition (CREATE statement) of a programmable object.

get_extended_properties

Reads extended properties (descriptions, metadata) on tables, columns, and other objects.

get_object_dependencies

Shows what an object references and what references it — upstream and downstream dependency graphs.

Tool

Description

get_plantuml_diagram

Generates a PlantUML ER diagram with tables, columns, PKs, and FK relationships. Saves to a .puml file. Supports compact mode, schema/table filtering, and a configurable table limit (max 200).

get_mermaid_diagram

Generates a Mermaid ER diagram with tables, columns, PKs, and FK relationships. Saves to a .mmd file. Supports compact mode, schema/table filtering, and a configurable table limit (max 200).

DBA Diagnostic Tools

Each toolkit is enabled independently via config flags and requires the corresponding stored procedures installed on the target SQL Server.

All DBA tools apply response size optimisation by default — XML query plan columns are excluded and long string values are truncated to keep responses within AI context window limits. Every tool supports these optional parameters:

Parameter

Description

verbose

Return all columns with no truncation.

includeQueryPlans

Include XML execution plan columns in the output.

maxRows

Maximum rows to return per result set. Available on tools with variable-length output: BlitzIndex, BlitzLock, HealthParser, LogHunter (default 200), IndexCleanup, QueryReproBuilder.

Some tools have additional parameters: includeXmlReports (BlitzLock, HealthParser, HumanEventsBlockViewer), compact (sp_WhoIsActive), verboseMetrics (QuickieStore).

Install from: github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit

Tool

Description

sp_blitz

Overall SQL Server health check — prioritized findings for performance, configuration, and security.

sp_blitz_first

Real-time performance diagnostics — samples DMVs over an interval for waits, file latency, and perfmon counters.

sp_blitz_cache

Plan cache analysis — top queries by CPU, reads, duration, executions, or memory grants.

sp_blitz_index

Index analysis — missing, unused, and duplicate indexes with usage patterns.

sp_blitz_who

Active query monitor — what's running, blocking info, tempdb usage, query plans.

sp_blitz_lock

Deadlock analysis from the system_health extended event session.

sp_blitz_plan_compare

Cross-server query plan comparison — captures a plan snapshot on one server and compares it to the cached plan on a second server without using linked servers. Requires the demon_hunters branch until merged to main.

Install from: github.com/erikdarling/DarlingData

Tool

Description

sp_pressure_detector

Diagnoses CPU and memory pressure — resource bottlenecks, high-CPU queries, memory grants, disk latency.

sp_quickie_store

Query Store analysis — top resource-consuming queries, plan regressions, wait statistics.

sp_quickie_cache

Plan cache analysis — high-impact queries ranked by impact score over the dm_exec_*_stats DMVs (the plan-cache companion to sp_quickie_store).

sp_health_parser

Parses the system_health extended event session for historical waits, disk latency, CPU, memory, and locking.

sp_log_hunter

Searches SQL Server error logs for errors, warnings, and custom messages.

sp_human_events_block_viewer

Analyzes blocking events from sp_HumanEvents sessions — blocking chains, lock details, waits.

sp_index_cleanup

Finds unused and duplicate indexes that are candidates for removal.

sp_query_repro_builder

Generates reproduction scripts for Query Store queries with parameter values.

Install from: whoisactive.com

Tool

Description

sp_whoisactive

Monitors active sessions and queries — wait info, blocking details, tempdb usage, resource consumption.

Progressive Discovery

When EnableDynamicToolsets is true, only core tools load at startup. Three meta-tools let the AI discover and enable additional toolsets on demand, reducing initial context window usage:

Tool

Description

list_toolsets

Lists available toolsets with status (available, enabled, not configured) and tool counts.

get_toolset_tools

Returns detailed tool and parameter info for a specific toolset before enabling it.

enable_toolset

Enables a toolset, making its tools available. Only works if the admin has enabled the toolset via the corresponding Enable* config flag.

Example flow:

  1. AI calls list_toolsets — sees first_responder_kit is "available" (configured but not yet enabled)

  2. AI calls get_toolset_tools("first_responder_kit") — reviews the 7 tools and their parameters

  3. AI calls enable_toolset("first_responder_kit") — the 7 tools are now registered and usable

  4. AI calls sp_blitz — runs the health check as normal

In static mode (EnableDynamicToolsets: false), all enabled toolsets load at startup and the discovery tools are not registered. Schema Exploration and Diagrams toolsets are always loaded regardless of mode.

Known limitation: Progressive discovery relies on the MCP notifications/tools/list_changed notification to inform clients that new tools have been registered. Claude Code does not currently handle this notification (anthropics/claude-code#4118), so dynamically enabled toolsets will not appear. Use static mode (EnableDynamicToolsets: false) when using Claude Code.

Security

Query Validation

Every query is parsed into an Abstract Syntax Tree (AST) using Microsoft's official TSql180Parser and must pass these rules:

  • Single statement only — multiple statements are rejected

  • SELECT only — INSERT, UPDATE, DELETE, DROP, EXEC, CREATE, ALTER, and all other statement types are blocked

  • No SELECT INTO — prevents table creation via SELECT

  • No external data access — OPENROWSET (all variants including BULK, Cosmos DB, and internal), OPENQUERY, OPENDATASOURCE, OPENXML blocked

  • No linked servers — four-part name references are rejected

  • No MAXRECURSION hint — prevents overriding the default recursion limit

  • Cross-database queries are allowed — three-part names work by design; the security boundary is the server, not the database. To restrict to a single database, limit the login's permissions.

Because validation operates on the parsed AST, it correctly handles edge cases that defeat string-based approaches: keywords inside comments, string literals, nested block comments, and encoding tricks.

Parameter Blocking

Diagnostic stored procedures execute via whitelisted procedure names with blocked parameters that prevent writes:

  • First Responder Kit — all @Output* parameters blocked (prevents writing results to server tables)

  • DarlingData — logging and output parameters blocked (prevents table creation and data retention)

  • sp_WhoIsActive — @destination_table, @return_schema, @schema, @help blocked

Rate Limiting

All tool executions are subject to concurrency limiting (MaxConcurrentQueries, default 5) and throughput limiting (MaxQueriesPerMinute, default 60). Excess requests are rejected with a retry message.

Connection Security

Use Windows Authentication or Azure Managed Identity where possible to avoid storing credentials in config files. When SQL Authentication is required, use environment variable overrides to inject credentials at runtime. See SECURITY.md for detailed guidance including credential stores and connection string encryption.

Known Risks

  • This project depends on the official Microsoft MCP C# SDK (ModelContextProtocol NuGet package, version 1.3.0). As the MCP framework handles all protocol I/O, any vulnerability in it directly affects this application's security boundary. Monitor the package for updates and upgrade when new versions are released.

  • The data returned from a SQL Server query could include malicious prompt injection targeting AIs. This is a risk of all AI use and cannot be mitigated by this project. Ensure you're following best practices for AI security and only connecting to trusted data sources.

Contributing

Contributions are welcome. See CONTRIBUTING.md for architecture details, development setup, testing instructions, and guidelines for adding new tools.

License

MIT

Available Tools

12 tools
describe_tableDescribe Table StructureA
Read-onlyIdempotent

Get comprehensive metadata about a single table including columns, data types, indexes, primary key, foreign keys, check constraints, and default constraints.

Inputs: tableName (required), serverName (required), databaseName (required), schemaName.

get_extended_propertiesGet Extended PropertiesA
Read-onlyIdempotent

Read extended properties (descriptions, metadata) from tables and columns. Returns JSON with schema, table, column, property name, and value.

Inputs: serverName (required), databaseName (required), tableName, columnName, +1 more.

get_mermaid_diagramGet Mermaid ER DiagramA

Generate a Mermaid ER diagram saved to a file. Shows tables, columns, PKs, and FK relationships with smart cardinality.

Inputs: outputPath (required), serverName (required), databaseName (required), compact, +5 more.

get_object_definitionGet Object DefinitionA
Read-onlyIdempotent

Get the T-SQL source code of a stored procedure, function, view, or trigger. Returns Markdown with the object type and definition.

Inputs: objectName (required), serverName (required), databaseName (required), schemaName.

get_object_dependenciesGet Object DependenciesA
Read-onlyIdempotent

Show what a database object references and what references it. Returns JSON with 'references' and 'referencedBy' arrays for dependency analysis.

Inputs: objectName (required), serverName (required), databaseName (required), schemaName.

get_plantuml_diagramGet Database ER DiagramA

Generate a PlantUML ER diagram saved to a file. Shows tables, columns, PKs, and FK relationships with smart cardinality.

Inputs: outputPath (required), serverName (required), databaseName (required), compact, +5 more.

get_query_planGet Query Execution PlanA
Idempotent

Get the estimated or actual XML execution plan for a SELECT query. Estimated plans show the optimizer's plan without executing. Actual plans execute the query and include runtime statistics. Uses the same query validation as read_data (SELECT only).

Inputs: query (required), outputPath (required), serverName (required), databaseName (required), +1 more.

get_schema_overviewGet Database Schema OverviewA
Read-onlyIdempotent

Markdown overview of database schema: tables, columns, types, PKs, FKs, unique/check constraints, defaults. Use get_plantuml_diagram for visual ER output or describe_table for single-table detail.

Inputs: serverName (required), databaseName (required), compact, maxTables, +4 more.

list_databasesList Databases on SQL ServerA
Read-onlyIdempotent

List all databases on a named SQL Server instance. Returns database names, IDs, states, and creation dates. Use list_servers first to discover available server names.

Inputs: serverName (required).

list_programmable_objectsList Programmable ObjectsA
Read-onlyIdempotent

List stored procedures, functions, views, and triggers in a database. Returns JSON with schema, name, type, and create/modify dates.

Inputs: serverName (required), databaseName (required), objectTypes, excludeSchemas, +1 more.

list_serversList SQL ServersA
Read-onlyIdempotent

List the available SQL Server instances that can be queried. Call this first to discover server names before using read_data.

Inputs: no named parameters.

read_dataRead Data from SQL ServerA
Read-onlyIdempotent

Execute a read-only SQL SELECT query against a named SQL Server instance. Only SELECT and WITH (CTE) queries are allowed. Use list_servers first to discover available server names. Small results are returned inline as JSON {truncated, rows}. Large results (over the configured row threshold, 500 by default, or about 40,000 characters) are written to a CSV file instead, and the response gives the file path, row count, column names and types, and a 10-row preview. Process a result file with code (e.g. Python csv/pandas, PowerShell Import-Csv) rather than reading it into context.

Inputs: query (required), serverName (required), databaseName (required), toFile.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools are clearly distinguished by resource and action (server, database, table, programmable object, query plan). The two diagram generators, get_plantuml_diagram and get_mermaid_diagram, overlap heavily in purpose and could cause misselection, though their output formats differ.

    Naming Consistency4/5

    Names use consistent snake_case and mostly follow a get_/list_ verb_noun pattern. Exceptions like read_data and describe_table are minor deviations that remain readable and predictable.

    Tool Count5/5

    12 tools is well within the appropriate range for a SQL Server exploration and metadata server. Each tool covers a distinct concern without obvious bloat or unnecessary duplication.

    Completeness4/5

    The surface covers core read-only SQL Server exploration: servers, databases, queries, query plans, table metadata, schema overview, diagrams, dependencies, and programmable objects. Minor gaps exist, such as no explicit list_tables primitive, but get_schema_overview and describe_table provide workarounds.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    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
      Read-only SQL Server MCP server enabling safe database queries, table listing, and schema inspection with built-in security protections.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Security-first, read-only MCP server for Microsoft SQL Server, enabling safe natural-language querying of databases.
      5
      9 npm
      MIT