mcp-sql-multi

One MCP server that fronts several SQL Server / Azure SQL / Synapse databases at once. Each tool takes a database argument naming a target declared in connections.json; call list_databases first to see what's available.

Tools

Related MCP server: mssql-explorer-mcp

Prerequisites

• Python 3.10+

• Microsoft ODBC Driver 18 for SQL Server — install from https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server (the connection strings use DRIVER={ODBC Driver 18 for SQL Server}).

• Network access / firewall allowance to each database server.

Setup (step by step)

1. Install

git clone https://github.com/rajivdatta/mcp-sql-multi.git
cd mcp-sql-multi
python -m venv .venv
.venv\Scripts\activate          # Windows  (source .venv/bin/activate on macOS/Linux)
pip install -r requirements.txt

2. Define your databases (connections.json)

Copy the example and edit it:

copy connections.example.json connections.json

connections.json is git-ignored (it holds your server names and logins). Each top-level key is a target name you'll pass to the tools. Example:

{
  "dev": {
    "server": "your-dev.database.windows.net",  // host
    "port": 1433,
    "database": "YourDevDb",
    "auth": "sql",                               // see auth modes below
    "user": "your_login",
    "password_env": "DEV_PASSWORD",              // env var holding the password
    "trust_cert": true,
    "readonly": false
  },
  "prod": {
    "server": "your-prod.database.windows.net",
    "port": 1433,
    "database": "YourProdDb",
    "auth": "aad-broker",                        // Windows WAM broker, silent after first sign-in, no secret
    "trust_cert": false,
    "readonly": true
  }
}

Per-target field reference

Auth modes (auth)

Tip: mark prod or shared targets "readonly": true.

3. Supply passwords (.env)

Only needed for sql targets. Copy .env.example to .env and set each variable you referenced via password_env:

DEV_PASSWORD=your-dev-sql-password

.env is git-ignored. aad-broker / aad-integrated / aad-interactive targets need no secret here.

4. Test a connection standalone

.venv\Scripts\activate
python -c "import db; print(db.list_targets())"               # config loads, targets listed
python -c "import server; print(server.list_tables('dev','dbo'))"   # real query against 'dev'

aad-broker targets sign in once via the Windows WAM broker, then connect silently on later runs; aad-interactive targets pop a browser sign-in on the first query of every new process.

5. Register with your MCP host

See examples/mcp.json — point command at the venv's Python and args at server.py. Keep passwords in this folder's .env, not in the host's env block: host config files are routinely pasted into issues and chat threads when troubleshooting, and a secret in one leaks with it.

{
  "mcpServers": {
    "sql-multi": {
      "command": "C:\\path\\to\\mcp-sql-multi\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-sql-multi\\server.py"],
      "env": {}
    }
  }
}

Restart your MCP client, then try: "using sql-multi, list databases" → "list tables in dev".

Use with Claude Desktop

Claude Desktop reads its MCP servers from claude_desktop_config.json. Open it from Settings → Developer → Edit Config (this creates the file if it doesn't exist), or edit it directly:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this server under mcpServers, using absolute paths to the venv's Python and server.py (passwords stay in .env, never in env):

{
  "mcpServers": {
    "sql-multi": {
      "command": "C:\\path\\to\\mcp-sql-multi\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-sql-multi\\server.py"],
      "env": {}
    }
  }
}

On macOS the paths are POSIX, e.g. "command": "/Users/you/mcp-sql-multi/.venv/bin/python". Save the file and fully quit and reopen Claude Desktop (use Quit from the tray/menu-bar icon — closing the window isn't enough). The server's tools then appear in the tools (🔌) menu of a new chat.

Safety

The readonly flag is a typo-catcher, not the security boundary. The real boundary is the permission set of the login behind each target. A keyword blocklist alone is bypassable — SELECT ... INTO t creates a table without using a blocked keyword, and T-SQL lets a stored procedure be invoked as the first statement of a batch with no EXEC at all. So:

• Back every read-only target with a read-only principal (db_datareader, or an explicit CONNECT + SELECT grant and nothing more). If the login can write, the target can be written to eventually, whatever this server does.

• In-server enforcement on read-only targets is two layers, applied after comments are stripped and string literals are blanked (so a keyword appearing in data no longer causes a false refusal):

  1. a blocklist of mutating/escalating/locking constructs — including INTO, sp_*/xp_*, OPENROWSET, WAITFOR and the lock hints; and

  2. an allowlist requiring every statement to open with SELECT, WITH, DECLARE, SET or PRINT, so unanticipated syntax is refused by default rather than permitted by omission.

• Results capped at 1000 rows, and a truncated result is labelled as such — do not total or summarise a result carrying that warning.

• 60-second query timeout.

• Connections use Encrypt=yes. Leave trust_cert at false for Azure SQL (it presents a valid certificate); true skips certificate validation and should be reserved for genuinely self-signed dev servers.

• connections.json and .env are git-ignored, so server names, logins, and passwords are never committed.

License

MIT (c) 2026 Rajiv Datta