SqlAugur

SqlAugur

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.

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 29 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.

NuGet Global Tool (recommended)

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

Security Note: appsettings.json is gitignored to prevent accidental credential commits. See SECURITY.md for recommended authentication methods including Windows Authentication, Azure Manage

…