SQLPad MCP Server

一个用于 SQLPad 的 MCP 服务器。将 AI 代理指向带有基础 URL 和服务令牌的 SQLPad 实例，代理即可发现连接、检查模式、运行 SQL 并管理已保存的查询。

要求

• Node.js 20 或更高版本。

• 一个可访问的 SQLPad 实例。

• SQLPad 服务器必须配置 SQLPAD_SERVICE_TOKEN_SECRET。否则，每个 Bearer 认证请求都会返回 401 Unauthorized。

• 在 SQLPad 管理界面中生成的服务令牌。

Related MCP server: SQLite Database MCP Server

快速开始

无需安装步骤——直接从 npm 运行：

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

或者全局安装：

npm install -g sqlpad-mcp

该服务器通过 stdio 使用 MCP 协议，因此通常由 MCP 客户端启动，而不是手动运行。直接运行它仍然有助于验证凭据：成功时，它会将检测到的 SQLPad 版本记录到 stderr。

配置

CLI 标志优先于相应的环境变量。批处理轮询间隔（250 毫秒）是内部的，不可配置。

Claude Code 配置

将服务器添加到你的 Claude Code mcp.json 中：

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

通过 env 提供令牌可使其不进入进程参数列表，因为该列表可通过 ps 被所有用户读取。

要启用受控工具组，请将 "SQLPAD_ALLOW_WRITES": "true" 或 "SQLPAD_ALLOW_ADMIN": "true" 添加到同一个 env 块中。

工具

始终注册十二个工具。另外六个工具受两个 SQLPAD_ALLOW_* 标志控制，默认关闭。

执行

发现

已保存的查询

已保存查询的写入 — 需要 SQLPAD_ALLOW_WRITES=true

管理 — 需要 SQLPAD_ALLOW_ADMIN=true

这些工具调用 SQLPad 端点，这些端点本身需要管理员服务令牌。

SQL 执行方式

SQLPad 通过异步批处理执行 SQL。创建批处理会立即返回；每条语句从 queued 变为 started，然后变为 finished 或 error。结果会为每条语句单独获取，并且在该语句完成之前不可用。

run_sql 工具吸收了完整协议——创建、轮询、获取和返回行——因此代理只需一次调用。如果轮询达到配置的超时时间，工具会返回一个 batchId，代理可以恢复执行而不是挂起。

连接可能没有默认数据库。请将表名限定为 schema.table，并使用 get_connection_schema 发现可用的模式。

安全性

• run_sql 执行任意 SQL，包括 DDL 和 DML，且不受沙箱保护。SQLPAD_ALLOW_WRITES 仅控制 SQLPad 自身已保存查询对象的修改；它不限制 SQL 内容。请在 SQLPad 连接本身使用只读数据库凭据。这是唯一真正的强制措施。

• SQLPad 的 /api/service-tokens 端点故意不暴露。生成凭据的工具是权限提升的原语。

• 管理工具默认关闭。

• 服务令牌会从所有错误和日志中编辑掉。所有日志都输出到 stderr，因为 stdout 是 JSON-RPC 通道。

• 批处理范围限定为令牌自己的用户，因此服务器只能看到自己的查询历史。

贡献

克隆仓库并安装依赖：

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

为你的更改创建分支。在打开拉取请求之前，运行：

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

CI 在 Node 20 和 22 上运行相同的三个命令。

许可证

MIT