mssqlcl

SQL Server and Azure SQL MCP server & CLI (.NET 10) with zero-config connection discovery from VS Code and Antigravity IDE (ms-mssql.mssql / SecretStorage), read-only lexical T-SQL guard by default, and token-efficient CSV output.

Documentation

mssqlcl logo

mssqlcl

SQL Server MCP Server & CLI with zero-config connection discovery for VS Code and Antigravity IDE.

Release .NET 10 Windows x64 MCP Protocol MIT License

Features • Prerequisites • Installation • MCP Setup • Tools (11) • CLI • Security


Configure your SQL Server connections once in VS Code, Antigravity IDE (ms-mssql.mssql), or via mssqlcl conn save, and expose them safely to any MCP-compatible AI client (Antigravity, Claude Desktop, Claude Code, Cursor, etc.) over stdio.

flowchart LR
    Client["AI Client<br/>(Antigravity / VS Code / Cursor / Claude)"] <-->|"stdio<br/>JSON-RPC 2.0"| Server["mssqlcl --mcp<br/>(Self-contained .NET 10)"]
    Server -->|"Zero-config discovery"| IDE["VS Code / Antigravity IDE<br/>(ms-mssql.mssql + SecretStorage)"]
    Server -->|"Fallback / Override"| Vault["Local DPAPI Vault<br/>(%USERPROFILE%\.mssqlcl)"]
    Server -->|"Read-only guard<br/>&amp; T-SQL"| SQL[("SQL Server /<br/>Azure SQL")]

🎥 Quick Demo — End-to-End in Antigravity

mssqlcl Antigravity Demo

✨ Features

CapabilityWhat it gives you
Zero-Config IDE DiscoveryAutomatically reads mssql.connections and mssql.connectionGroups (JSONC) from Antigravity IDE, VS Code, and %USERPROFILE%\.mssqlcl\connections.json.
Automatic Credential ResolutionSupports Windows Auth (Integrated), SQL Login (SqlLogin) via Electron SecretStorage (Local State DPAPI + state.vscdb AES-256-GCM) or local DPAPI vault, and Microsoft Entra ID / MFA (AzureMFA).
11 Multi-Connection MCP ToolsFull server discovery, connection management, schema/object inspection, and query execution keyed by connectionId.
Token-Efficient OutputCompact CSV output by default (optional json) with --max-rows capping (default 500) to minimize LLM token usage.
Read-Only Lexical Guard--readonly enabled by default: skips comments, string literals, and quoted identifiers while blocking DML/DDL/execution keywords (INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, CREATE, TRUNCATE, EXEC, SELECT ... INTO, etc.).
Clean stdio & Local AuditDiagnostics go exclusively to stderr. Queries are logged locally to JSONL at %USERPROFILE%\.mssqlcl\audit.log without touching target databases or logging secrets.

📋 Prerequisites

  • Operating System: Windows 10 / 11 (x64) — required for Windows DPAPI and Electron SecretStorage decryption.
  • Connection Source (choose one):
    • Recommended (Zero-Config): VS Code or Antigravity IDE with the SQL Server (ms-mssql.mssql) extension and your connections already saved.
    • Standalone (No IDE required): Manage profiles directly via mssqlcl conn save (stored in %USERPROFILE%\.mssqlcl\ encrypted with Windows DPAPI) or MSSQLCL_PWD_<PROFILE> environment variables.
  • Runtime:
    • End users (Release ZIP / Installer): No .NET installation required (self-contained binary).
    • Building from source: .NET 10 SDK.

[!TIP] If you already use the ms-mssql.mssql extension in VS Code or Antigravity IDE, you don't need to re-enter passwords or maintain separate connection strings—mssqlcl discovers them automatically.


📦 Installation

Option 1: One-Command Online Installer (PowerShell, no .NET SDK required)

irm https://raw.githubusercontent.com/codevswia/mssqlcl/main/scripts/install.ps1 | iex

Downloads the latest release ZIP to %LOCALAPPDATA%\Programs\mssqlcl and adds it to your User PATH (no Administrator privileges required).

Option 2: Portable ZIP (Offline — Zero system changes or User PATH)
  1. Download mssqlcl-vX.Y.Z-win-x64.zip from GitHub Releases.
  2. Extract it anywhere (for example C:\tools\mssqlcl\).
  3. Choose how you want to run it:
    • Portable (zero system changes): Point your MCP config directly to C:\tools\mssqlcl\mssqlcl.exe (no PATH changes).
    • Install to User PATH (no Admin required): Double-click install.cmd (or run powershell -ExecutionPolicy Bypass -File .\install-local.ps1) to copy mssqlcl.exe to %LOCALAPPDATA%\Programs\mssqlcl and add it to your User PATH. Restart your IDE afterwards if it was already open.
    • Offline via main installer: .\scripts\install.ps1 -LocalZip path\to\mssqlcl-vX.Y.Z-win-x64.zip
Option 3: Build & Install from Source (requires .NET 10 SDK)
# Build & run unit tests
dotnet test

# Build and install mssqlcl.exe to %LOCALAPPDATA%\Programs\mssqlcl and add to User PATH
.\scripts\install.ps1 -FromSource

# Or build a standalone self-contained binary from source
.\scripts\install.ps1 -FromSource -SelfContained

🔌 MCP Client Configuration

Add mssqlcl to your MCP client configuration (such as Antigravity IDE mcp_config.json, Claude Desktop claude_desktop_config.json, or Cursor):

{
  "mcpServers": {
    "mssqlcl": {
      "command": "mssqlcl",
      "args": ["--mcp"]
    }
  }
}

[!NOTE] If you installed mssqlcl in portable mode without adding it to PATH, replace "mssqlcl" in "command" with the full path (e.g. "C:\\tools\\mssqlcl\\mssqlcl.exe").

Optional MCP Flags

FlagDefaultDescription
--readonlyenabledBlocks DML/DDL/EXEC statements via lexical T-SQL inspection
--readwriteoffAllows write/DDL statements in mssql_run_query
--max-rows <N>500Caps returned rows per result set
--timeout <sec>30Default SQL command timeout in seconds
--source <mode>autoauto, antigravity, vscode, or local
--no-auditoffDisables writing to %USERPROFILE%\.mssqlcl\audit.log

🎬 Video Walkthroughs

🚀 Antigravity (IDE + App) — Full Walkthroughs
▶️ Guide 1: SQL Login — Save connection, install mssqlcl MCP & query SQL Server (3m 41s)

https://github.com/user-attachments/assets/b5a99cef-7ed1-4fe2-acab-0bd34b7e16ae

▶️ Guide 2: Microsoft Entra ID / MFA — Save Azure SQL MFA connection, install MCP & query with AI (3m 38s)

https://github.com/user-attachments/assets/1ff4a37a-32d5-432e-9a07-061de0f1503d

💻 VS Code — Full Walkthroughs (Coming Soon)

Walkthroughs for VS Code (ms-mssql.mssql) coming soon.


🛠️ MCP Tools Reference

mssqlcl exposes 11 database tools to your AI assistant, supporting multiple simultaneous connections via connectionId:

CategoryToolDescription
Discoverymssql_list_serversLists discovered SQL Server profiles from Antigravity IDE, VS Code, and local vault
Connectionmssql_connectOpens a connection to a profile and returns a connectionId
Connectionmssql_disconnectCloses an active connectionId session
Connectionmssql_get_connection_detailsReturns active connection metadata (server, database, auth type, state)
Connectionmssql_change_databaseSwitches the active database context (USE <db>) for a connectionId
Schemamssql_list_databasesLists databases on the connected SQL Server instance
Schemamssql_list_schemasLists schemas in the current database
Schemamssql_list_tablesLists tables (with schema and metadata)
Schemamssql_list_viewsLists views in the current database
Schemamssql_list_functionsLists scalar/table-valued functions
Querymssql_run_queryExecutes T-SQL (protected by --readonly guard by default, CSV/JSON output)

💻 CLI Usage

Use the CLI directly to verify your environment, inspect discovered IDE profiles, or manage local DPAPI credentials:

# Verify environment, IDE discovery paths, and local vault health
mssqlcl doctor

# List discovered profiles and credential resolution status
mssqlcl conn list

# Test live connectivity for a profile (prefix with antigravity: or vscode: if duplicated)
mssqlcl conn test "MyServer\MyDatabase"
mssqlcl conn test "vscode:MyServer\MyDatabase"

# Create a local profile or store a DPAPI-protected password override
mssqlcl conn save --profile "LocalDev" --server "localhost\SQLEXPRESS" --database "AppDb" --user "sa" --savepwd
mssqlcl conn save --profile "ExistingIdeProfile" --savepwd

# Delete a local profile
mssqlcl conn delete "LocalDev"

🔒 Security

[!IMPORTANT] Only pass --readwrite against databases where write or DDL operations are explicitly intended.

  • Zero plaintext secret leaks: mssqlcl never writes decrypted passwords to disk, stdout, stderr, or audit.log.
  • Safe IDE vault reading: state.vscdb is copied to a temporary file in read-only mode before querying and deleted immediately afterwards, so it works safely even while VS Code or Antigravity IDE is running.
  • Zero target database footprint: Audit logs are stored strictly locally at %USERPROFILE%\.mssqlcl\audit.log.

👤 Author & Organization

📄 License

Distributed under the MIT License — see LICENSE for details.