如何用 MCP Toolbox 在本地跑通 PostgreSQL 自定义工具并用 MCP Inspector 验证工具列表-平芜编程栈

如何用 MCP Toolbox 在本地跑通 PostgreSQL 自定义工具并用 MCP Inspector 验证工具列表

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

这条路径对应一个具体的首次使用任务：在本地准备一个 PostgreSQL 数据库，下载 MCP Toolbox for Databases 二进制，在tools.yaml中定义指向该数据库的自定义postgres-sql工具，启动 Toolbox 服务器，最后用 MCP Inspector 通过tools/list确认自定义工具都出现在工具列表中。适用前提是本地已安装 PostgreSQL 16+ 和psql客户端，且能通过npx运行 MCP Inspector（Node.js 环境）。文档同时要求：通过 MCP 使用 Toolbox 时版本需在 0.3.0 以上，本文使用 1.11.0 二进制。

准备条件

开始前确认三件事：

PostgreSQL 16+ 与psql已安装，且数据库服务正在运行。若连接被拒绝（Connection refused），在 Linux 上可用sudo systemctl status postgresql查看状态、sudo systemctl start postgresql启动服务；
机器上有curl与chmod（下载并启用二进制）；
已安装 Node.js，可以执行npx（MCP Inspector 的运行方式）。

如果psql -U postgres提示密码或报FATAL: role "postgres" does not exist，说明你的安装使用了其他认证方式。文档给出的通用做法是切换到postgres操作系统用户（peer 认证），在本地连接时通常无需密码：

sudo -i -u postgres psql -h 127.0.0.1

进入psql后执行下面的建库步骤，结束后先输入\q退出psql，再输入exit回到普通用户 shell。

创建数据库、用户和示例数据

按 MCP 快速入门的步骤，用psql连接到本地 PostgreSQL（postgres为默认的超级用户角色）：

psql -h 127.0.0.1 -U postgres

创建 Toolbox 要使用的专用用户和数据库，并把库的所有权交给该用户。文档同时提示：真实应用中应遵循最小权限原则，只授予应用需要的权限。

CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user;

输入\q结束会话，然后用新用户连接新库：

psql -h 127.0.0.1 -U toolbox_user -d toolbox_db

在toolbox_db中创建文档使用的hotels表并插入 10 条示例数据（示例数据来自文档，仅用于演示工具调用）：

CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');

再次输入\q结束会话。至此数据库侧就绪：toolbox_db库、toolbox_user用户（密码my-password）、hotels表。

下载 Toolbox 二进制并编写 tools.yaml

下载对应操作系统和 CPU 架构的二进制。下面以linux/amd64为例，文档给出的版本为 1.11.0，OS可选值包括linux/amd64、darwin/arm64、darwin/amd64、windows/amd64、windows/arm64，其他架构可查阅文档中的发布页说明：

export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, windows/amd64, or windows/arm64 curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.11.0/$OS/toolbox

文档还建议（可选）在下载后验证二进制完整性，例如 Linux 上下载同目录的toolbox.asc签名文件、导入 Google 公钥后执行gpg --verify toolbox.asc toolbox，macOS 上执行codesign -v --verbose=4 toolbox。这一步会下载额外的签名文件或公钥，属于自愿的安全校验。

让二进制可执行（Linux 和 macOS）：

chmod +x toolbox

把以下内容写入tools.yaml。文档明确提醒：如果你在上一步自定义了user、password或database，这里要同步修改；实践中建议用${ENV_NAME}形式的环境变量替换来代替硬编码密钥。配置里包含一个kind: source的 PostgreSQL 数据源、五个kind: tool的自定义postgres-sql工具，以及一个kind: toolset工具集：

kind: source name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tool name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tool name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tool name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tool name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tool name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolset name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel

几个配置要点，依据 Tools 配置文档：

statement中的$1是 PostgreSQL 预编译语句占位符，参数按parameters列表顺序绑定，这也是文档建议的防 SQL 注入方式；
参数默认是必填的（省略required等同required: true）；若调用时缺少必填参数，会得到parameter "airline" is required一类的报错（这是文档示例中的提示格式）；
kind: toolset只是把工具逻辑分组，方便按 Toolset 文档所说的方式供不同 agent 加载。文档同时提示 toolset 是仅含工具的 group，新配置建议迁移到kind: group（可用toolbox migrate自动转换），但kind: toolset仍然可用。

启动 Toolbox 服务器

在tools.yaml所在目录启动服务器：

./toolbox --config "tools.yaml"

Toolbox 默认启用配置动态重载，如需关闭可加--disable-reload。按 MCP Client 文档，HTTP 客户端连接的端点是http://127.0.0.1:5000/mcp；如果只想暴露某个工具集，可用http://127.0.0.1:5000/mcp/{toolset_name}。

用 MCP Inspector 验证工具列表

在另一个终端运行 Inspector：

npx @modelcontextprotocol/inspector

提示安装 inspector 包时输入y。启动成功后终端会显示类似下面的内容（文档示例，<YOUR_SESSION_TOKEN>是本次会话实际生成的 token，需记录下来）：

Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: <YOUR_SESSION_TOKEN> Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<YOUR_SESSION_TOKEN>

在浏览器中打开该链接，然后在 Inspector 页面做如下设置：

Transport Type选择Streamable HTTP；
URL填写http://127.0.0.1:5000/mcp；
Configuration→Proxy Session Token确认填入的是刚才记录的那个<YOUR_SESSION_TOKEN>；
点击Connect；
选择List Tools。

成功条件：List Tools返回的工具列表中包含tools.yaml里配置的 5 个工具——search-hotels-by-name、search-hotels-by-location、book-hotel、update-hotel、cancel-hotel。看到它们即说明自定义工具已被 Toolbox 加载并可被 MCP 客户端发现。文档在 MCP 快速入门的对应位置给出了 Inspector 连接界面与工具列表的截图（inspector.png、inspector_tools.png，位于docs/en/documentation/getting-started/mcp_quickstart/目录），可对照确认界面状态。此时也可以直接在 Inspector 里对工具发起调用做初步测试。

限制与替代路径

stdio 方式：Toolbox 也支持 stdio 传输。如果改用 stdio，需以./toolbox --stdio启动（日志默认warn级别，不支持debug/info），Inspector 则用npx @modelcontextprotocol/inspector ./toolbox --stdio将其作为子进程运行，Transport Type选STDIO，Command填./toolbox（或二进制实际路径），Arguments填--stdio。本文主路径使用 HTTP 方式，两种传输不要混用。
协议版本：HTTP with SSE 端点（/mcp/sse）仅用于2024-11-05协议版本且已废弃，本文不使用。
MCP 不支持的特性：Toolbox 的 Authenticated Parameters 和 Authorized Invocations 不在 MCP 的 auth 规范支持范围内；带安全参数（secure: true）的工具只对协商了com.google.cloud/toolbox.v1扩展的客户端出现在tools/list中，未协商的客户端会看不到这些工具。本文示例工具均未使用安全参数，因此不影响列表验证。