sql-explorer-mcp

Read-only Model Context Protocol server for SQL databases. Lets LLMs (Claude, Cursor, ChatGPT, Continue) introspect and query SQL Server, Postgres, and SQLite with three layers of safety:

1. Connection-level read-only — pyodbc readonly=True, Postgres SET TRANSACTION READ ONLY
2. AST validation — sqlglot parses every query and rejects anything that isn't a SELECT (catches DML smuggled in CTEs)
3. Linter pass — sql-sop checks every query and rejects error-severity findings; warnings are surfaced to the LLM as advisory output

Multi-server: configure several databases in one servers.yaml, the LLM picks which one to target per call.

Tools exposed to the LLM

All tools accept an optional server to target a specific entry from servers.yaml. Default server is used when omitted.

Install

pip install sql-explorer-mcp
# or
pipx install sql-explorer-mcp

For SQL Server, install Microsoft ODBC Driver 18. Postgres and SQLite drivers ship as dependencies.

Configure

Copy servers.example.yaml to servers.yaml and edit. Passwords are read from environment variables, never stored in the file.

default_server: lab

servers:
  lab:
    dialect: mssql
    host: localhost
    port: 1433
    database: BusinessLab
    auth: sql
    username: sa
    password_env: SQL_EXPLORER_LAB_PASSWORD

  production:
    dialect: mssql
    host: BUSINESS-SQL
    database: SI
    auth: windows               # uses Trusted_Connection
    max_rows: 500

  warehouse:
    dialect: postgres
    host: db.internal
    database: warehouse
    username: readonly
    password_env: WAREHOUSE_PG_PASSWORD

The config file is searched in this order:

1. $SQL_EXPLORER_CONFIG if set
2. ./servers.yaml (current directory)
3. ~/.sql-explorer-mcp/servers.yaml

Run

As an MCP server for Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sql-explorer": {
      "command": "sql-explorer-mcp",
      "env": {
        "SQL_EXPLORER_CONFIG": "/full/path/to/servers.yaml",
        "SQL_EXPLORER_LAB_PASSWORD": "your-lab-password"
      }
    }
  }
}

Restart Claude Desktop. The seven tools appear under Settings → Tools.

As an MCP server for Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "sql-explorer": {
      "command": "sql-explorer-mcp",
      "env": { "SQL_EXPLORER_CONFIG": "/full/path/to/servers.yaml" }
    }
  }
}

Standalone (debug)

sql-explorer-mcp

Reads stdin/stdout in MCP protocol. Use the MCP Inspector to test interactively:

npx @modelcontextprotocol/inspector sql-explorer-mcp

Safety architecture

LLM submits SQL
       │
       ▼
┌──────────────────┐
│ Layer 2 (sqlglot)│  Parse, reject if not exactly one SELECT
└────────┬─────────┘  Catches: INSERT, UPDATE, DELETE, MERGE, EXEC,
         │            CREATE, DROP, ALTER, smuggled DML in CTEs,
         │            multiple statements
         ▼
┌──────────────────┐
│ Layer 3 (sql-sop)│  Lint, reject if any error-severity findings
└────────┬─────────┘  Warnings (W*) returned as advisory output,
         │            don't block execution.
         ▼
┌──────────────────┐
│ Layer 1 (driver) │  pyodbc readonly=True / Postgres SET TXN READ ONLY
└────────┬─────────┘  Final defence at the protocol layer.
         ▼
   Database
         │
         ▼
   Result rows (capped at server.max_rows)

Failure at any layer returns a structured result the LLM can read and react to:

{
  "passed": false,
  "layer": "select-only",
  "reason": "Forbidden statement type in query: Delete"
}

Why this design

• Read-only by enforcement, not convention. A misconfigured login isn't your only protection.
• Multi-engine from day 1. Same tool surface across SQL Server, Postgres, SQLite. Same servers.yaml.
• Multi-server in one process. Switch between lab and production by passing server="production" instead of restarting.
• Linter-aware. Uses sql-sop to flag patterns that compile fine but signal poor query habits (SELECT *, unbounded queries, etc.).
• Result caps. Every tool clamps row counts (max 1000 default) so a curious LLM can't pull 100k rows into context.

Comparison to other SQL MCP servers

Development

git clone https://github.com/Pawansingh3889/sql-explorer-mcp
cd sql-explorer-mcp
pip install -e ".[dev]"
pytest -v

License

MIT