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_SECRETconfigured. Without it, every Bearer-authenticated request returns401 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
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_sqlexecutes arbitrary SQL, including DDL and DML, and is not sandboxed.SQLPAD_ALLOW_WRITESonly 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-tokensendpoints 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.
