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.

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

| Env var | CLI flag | Default | Meaning | | --- | --- | --- | --- | | SQLPAD_BASE_URL | --base-url | (required) | Base URL of the SQLPad instance; a subpath mount is supported. | | SQLPAD_SERVICE_TOKEN | --token | (required) | Service token, sent as Authorization: Bearer. | | SQLPAD_ALLOW_WRITES | --allow-writes | false | Register the saved-query write tools. | | SQLPAD_ALLOW_ADMIN | --allow-admin | false | Register the admin-only tools. | | SQLPAD_MAX_ROWS | --max-rows | 500 | Cap on rows returned per statement. | | SQLPAD_TIMEOUT_MS | --timeout-ms | 60000 | How long to poll a batch before returning a resumable batchId. |

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

| Tool | Description | | --- | --- | | run_sql | Execute arbitrary SQL, including DDL and DML, by creating an asynchronous SQLPad batch, polling it to completion, and returning rows inline. Not sandboxed. Rows are capped by maxRows and truncation is reported explicitly. On timeout it returns a batchId so execution can be resumed rather than re-run. A failed statement carries an error.hint when the cause is recognizable, such as a table name that needs schema. qualification. | | get_batch | Get a batch and its current statement statuses. Call this after run_sql times out, or while a batch is still queued or running. | | get_statement_results | Page through a large finished statement result instead of re-running the query. Returns a bounded page converted to objects using the statement's column names. | | cancel_batch | Request cancellation of an asynchronous batch. SQLPad rejects cancellation when the connection does not support asynchronous execution. |

Discovery

| Tool | Description | | --- | --- | | list_connections | List the connections available to the service token. Works with a non-admin token, unlike get_connection. | | get_connection_schema | Get a bounded database schema for a connection. Unfiltered full-schema output can be enormous — prefer schemaFilter or tableFilter, and use summary mode unless column details are needed. | | list_drivers | List SQLPad database drivers, bounded by the requested limit. |

Saved queries

| Tool | Description | | --- | --- | | list_queries | List saved queries using optional connection, text, tag, ownership, creator, and sort filters. | | get_query | Get one saved query by ID. | | list_tags | List distinct saved-query tags, with bounded local pagination. | | list_query_history | List the calling user's query history, newest first, with bounded local pagination. | | format_sql | Format SQL text using SQLPad. Older SQLPad servers may not provide this endpoint. |

Saved-query writes — requires SQLPAD_ALLOW_WRITES=true

| Tool | Description | | --- | --- | | create_query | Create a saved query. | | update_query | Replace the editable fields of an existing saved query. | | delete_query | Permanently delete a saved query. |

Admin — requires SQLPAD_ALLOW_ADMIN=true

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

| Tool | Description | | --- | --- | | get_connection | Get one connection by ID. | | test_connection | Test a connection configuration without saving it. | | list_users | List SQLPad users, with explicit output bounds. |

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