SQLPad MCP Server

An MCP server for SQLPad. Point an AI agent at a SQLPad instance with its base URL and a service token, and the agent can discover connections, inspect schemas, run SQL, and manage saved queries.

Requirements

• Node.js 20 or later.

• A reachable SQLPad instance.

• The SQLPad server must have SQLPAD_SERVICE_TOKEN_SECRET configured. Without it, every Bearer-authenticated request returns 401 Unauthorized.

• A service token generated in the SQLPad admin GUI.

Related MCP server: SQLite Database MCP Server

Quick start

No install step is needed — run it straight from npm:

SQLPAD_SERVICE_TOKEN=... npx sqlpad-mcp --base-url https://sqlpad.example.com

Or install it globally:

npm install -g sqlpad-mcp

The server speaks MCP over stdio, so it is normally launched by an MCP client rather than by hand. Running it directly is still useful to verify credentials: on success it logs the detected SQLPad version to stderr.

Configuration

A CLI flag takes precedence over the corresponding environment variable. The batch poll interval (250 ms) is internal and not configurable.

Claude Code configuration

Add the server to your Claude Code mcp.json:

{
  "mcpServers": {
    "sqlpad": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "sqlpad-mcp",
        "--base-url",
        "https://sqlpad.example.com"
      ],
      "env": {
        "SQLPAD_SERVICE_TOKEN": "..."
      }
    }
  }
}

Supplying the token through env keeps it out of the process argument list, which is world-readable through ps.

To enable the gated tool groups, add "SQLPAD_ALLOW_WRITES": "true" or "SQLPAD_ALLOW_ADMIN": "true" to the same env block.

Tools

Twelve tools are always registered. Six more are gated behind the two SQLPAD_ALLOW_* flags and are off by default.

Execution

Discovery

Saved queries

Saved-query writes — requires SQLPAD_ALLOW_WRITES=true

Admin — requires SQLPAD_ALLOW_ADMIN=true

These call SQLPad endpoints that themselves require an admin service token.

How SQL execution works

SQLPad executes SQL through asynchronous batches. Creating a batch returns immediately; each statement moves from queued to started, then to finished or error. Results are fetched separately for each statement and are unavailable until that statement is finished.

The run_sql tool absorbs the full protocol — create, poll, fetch, and return rows — so an agent makes one call. If polling reaches the configured timeout, the tool returns a batchId that the agent can resume with instead of hanging.

Connections may have no default database. Qualify table names as schema.table, and use get_connection_schema to discover available schemas.

Security

• run_sql executes arbitrary SQL, including DDL and DML, and is not sandboxed. SQLPAD_ALLOW_WRITES only gates mutation of SQLPad's own saved-query objects; it does not restrict SQL content. Use read-only database credentials on the SQLPad connection itself. That is the only real enforcement.

• SQLPad's /api/service-tokens endpoints are deliberately not exposed. A tool that mints credentials is a privilege-escalation primitive.

• Admin tools are off by default.

• The service token is redacted from all errors and logs. All logging goes to stderr because stdout is the JSON-RPC channel.

• Batches are scoped to the token's own user, so the server only ever sees its own query history.

Contributing

Clone the repo and install dependencies:

git clone https://github.com/VAIBHAV7500/sqlpad-mcp.git
cd sqlpad-mcp
npm install
npm run build

Create a branch for your change. Before opening a pull request, run:

npm run typecheck && npm run lint && npm test

CI runs the same three commands on Node 20 and 22.

License

MIT