MCP Toolbox：把数据库接到 MCP 客户端，预置工具与 tools.yaml 自定义
- 仓库：https://github.com/googleapis/mcp-toolbox （原名 genai-toolbox，已改名）
- 文档：https://mcp-toolbox.dev/
- Releases：https://github.com/googleapis/mcp-toolbox/releases
- 许可：Apache-2.0
它是什么
MCP Toolbox for Databases 是一个开源的 Model Context Protocol (MCP) 服务器，把 AI agent、IDE 和应用连到企业数据库。它有两个用途：
- 开箱即用的 MCP 服务器（构建期）：用预置的通用工具，把 Gemini CLI、Google Antigravity、Claude Code、Codex 等 MCP 客户端直接连到数据库，做对话式查询、schema 探索、生成代码，不必写样板代码。
- 自定义工具框架（运行期）：为生产 agent 构建专门、更安全的 AI 工具，定义结构化查询、语义搜索和 NL2SQL，控制权限与参数。
为什么用它
- 开箱即用的数据库访问：预置通用工具（如
list_tables、execute_sql），在 IDE/CLI 里直接探索数据。 - 自定义工具框架：用自定义逻辑构建生产就绪的工具，通过受限访问、结构化查询、语义搜索保证安全。
- 简化开发：不到 10 行代码即可接入 ADK、LangChain、LlamaIndex 或自定义 agent。
- 性能：内置连接池、集成认证（IAM）、端到端可观测性（OpenTelemetry）。
- 可观测性：开箱即用的指标与 tracing，支持 OpenTelemetry。
预置工具快速接入
把下面的配置加到 MCP 客户端配置文件（通常是 mcp.json 或 claude_desktop_config.json）：
{
"mcpServers": {
"toolbox-postgres": {
"command": "npx",
"args": ["-y", "@toolbox-sdk/server", "--prebuilt=postgres", "--stdio"]
}
}
}
设置对应环境变量即可连接。使用 --prebuilt= 时立刻得到该数据库的标准工具；也可以用 --prebuilt=/ 只加载某组工具，例如 --prebuilt=postgres/data 只加载 SQL 工具。
支持的数据库：
- Google Cloud 侧：AlloyDB、BigQuery、Cloud SQL (PostgreSQL/MySQL/SQL Server)、Spanner、Firestore、Knowledge Catalog（原 Dataplex）
- 其它：PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、MongoDB、Redis、Elasticsearch、CockroachDB、ClickHouse、Couchbase、Neo4j、Snowflake、Trino 等
托管方案：Google Cloud MCP Servers。
自定义工具
自定义工具主要通过 tools.yaml 配置，用 --config tools.yaml 指定加载。
Sources：定义数据源
kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password
Tools：定义 agent 能做什么
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 || '%';
Toolsets：把工具分组，便于按 agent/应用加载
kind: toolset
name: my_first_toolset
tools:
- my_first_tool
- my_second_tool
---
kind: toolset
name: my_second_toolset
tools:
- my_second_tool
- my_third_tool
Prompts：用于与 LLM 交互的提示
kind: prompt
name: code_review
description: "Asks the LLM to analyze code quality and suggest improvements."
messages:
- content: >
Please review the following code for quality, correctness,
and potential improvements: \n\n{{.code}}
arguments:
- name: "code"
description: "The code to review"
Resources / resourceTemplates
只读内容、文件或参数化目录树，供 MCP 客户端发现与读取：
kind: resource
name: database_schema_ddl
type: text
description: "Core table definitions and constraints."
mimeType: text/x-sql
text: |
CREATE TABLE customers (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
);
---
kind: resource
name: database_schema
type: file
description: "PostgreSQL schema definition."
path: "./schema.sql"
---
kind: resourceTemplate
name: server_logs
type: file
description: "Application log files."
uriTemplate: "file:///var/log/{path}"
allowedPaths:
- "/var/log"
安装与运行
npx 直接运行：
npx @toolbox-sdk/server --config tools.yaml
这种方式方便，但性能不是最优，正式环境建议用二进制或容器。
二进制（以 Linux AMD64 为例，其它平台见 releases 页）：
export VERSION=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Homebrew：
brew install mcp-toolbox
容器：
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
源码安装：
go install github.com/googleapis/mcp-toolbox@v1.13.1
运行二进制：
./toolbox --config "tools.yaml"
默认开启动态重载，可用 --disable-reload 关闭。
容器运行：
docker run -p 5000:5000 -v $(pwd)/tools.yaml:/app/tools.yaml \
us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
--config "/app/tools.yaml"
Gemini CLI 扩展：
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox
连接到 Toolbox
MCP 客户端配置：
{
"mcpServers": {
"toolbox": {
"type": "http",
"url": "http://127.0.0.1:5000/mcp"
}
}
}
连接指定 toolset 时，把 url 换成 http://127.0.0.1:5000/mcp/{toolset_name}。
SDK 用于把工具加载进应用。
Python（toolbox-core）：
pip install toolbox-core
from toolbox_core import ToolboxClient
async with ToolboxClient("http://127.0.0.1:5000") as client:
tools = await client.load_toolset("toolset_name")
LangChain/LangGraph：
pip install toolbox-langchain
LlamaIndex：
pip install toolbox-llamaindex
JS/TS（@toolbox-sdk/core）：
npm install @toolbox-sdk/core
import { ToolboxClient } from '@toolbox-sdk/core';
const URL = 'http://127.0.0.1:5000';
let client = new ToolboxClient(URL);
const tools = await client.loadToolset('toolsetName');
Genkit、ADK 亦有对应包。Go SDK 见 https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go 。
安全与取舍
- 数据库访问走集成认证（IAM），自定义工具通过受限访问、结构化查询与语义搜索约束参数和权限范围。
- resource / resourceTemplate 是只读内容，file 类型可以用
allowedPaths限定可读路径（如/var/log）。 - 部署方式上，npx 启动快但性能非最优；正式环境用二进制或容器，容器映射
5000端口并以--config指定挂载的tools.yaml。 - 内置连接池与 OpenTelemetry 指标、tracing，省去自行接入的额外组件。