32 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理,属于社区翻译,非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
MCP Toolbox for Databases 是一款开源的 Model Context Protocol(MCP)服务器,可将你的 AI 智能体、IDE 和应用程序直接连接至企业数据库。
它具有双重用途:
- 开箱即用的 MCP 服务器(构建时,Build-Time): 使用我们预构建的通用工具,即可让 Gemini CLI、Google Antigravity、Claude Code、Codex 或其他 MCP 客户端即时连接你的数据库。无需编写样板代码,即可与数据对话、探索 schema 并生成代码。
- 自定义工具框架(运行时,Run-Time): 一套稳健的框架,用于为生产环境中的智能体构建专用、高安全性的 AI 工具。可安全、便捷地定义结构化查询、语义搜索和 NL2SQL 能力。
本 README 提供简要概览。如需全面了解,请参阅完整文档.
Important
仓库名称更新:
genai-toolbox仓库已正式更名为mcp-toolbox。为确保本地环境反映新名称,你可以更新远程地址:git remote set-url origin https://github.com/googleapis/mcp-toolbox.git
Note
该解决方案最初名为「Gen AI Toolbox for Databases」(github.com/googleapis/genai-toolbox),因其最初开发早于 MCP,后已更名以与 MCP 兼容对齐。
目录
为何选择 MCP Toolbox?
- 开箱即用的数据库访问: 预构建的通用工具,可让你直接从 IDE 或 CLI 即时探索数据(例如
list_tables、execute_sql)。 - 自定义工具框架: 使用你预定义的逻辑构建可用于生产环境的工具,并通过受限访问(Restricted Access)、结构化查询(Structured Queries)和语义搜索(Semantic Search)确保安全。
- 简化开发: 用不到 10 行代码即可将工具集成到 Agent Development Kit(ADK)、LangChain、LlamaIndex 或自定义智能体中。
- 更佳性能: 开箱即用支持连接池、集成身份验证(IAM)和端到端可观测性(OpenTelemetry)。
- 增强安全性:集成身份验证,更安全地访问你的数据。
- 端到端可观测性:开箱即用的指标与追踪,内置 OpenTelemetry 支持。
快速入门:预构建工具
告别频繁切换上下文,让你的 AI 助手成为真正的协作开发者。通过 MCP Toolbox 将 IDE 连接到数据库,你可以用自然语言查询数据、自动化 schema 发现与管理,并生成具备数据库感知能力的代码。
你可以在任何兼容 MCP 的 IDE 或客户端(例如 Gemini CLI、Google Antigravity、Claude Code、Codex 等)中,通过配置 MCP 服务器来使用 Toolbox。
预构建工具也可通过 Google Antigravity MCP Store 一键安装,使用更便捷。
-
将以下内容添加到你的客户端 MCP 配置文件(通常为
mcp.json或claude_desktop_config.json):{ "mcpServers": { "toolbox-postgres": { "command": "npx", "args": [ "-y", "@toolbox-sdk/server", "--prebuilt=postgres", "--stdio" ] } } } -
设置相应的环境变量以完成连接,请参阅预构建工具参考.
当你使用 --prebuilt=<database> 标志运行 Toolbox 时,即可即时获得与该数据库交互的标准工具。你也可以使用 --prebuilt=<database>/<toolset> 语法指定特定工具集(例如 --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 等。
有关所有受支持数据库的可用工具及其能力的完整列表,请参阅预构建工具参考.
有关 Docker 或二进制文件等不同运行方式,请参见安装并运行 Toolbox 服务器一节。
Tip
如需托管方案,Google Cloud MCP Servers 提供带有预构建工具的托管 MCP 体验;你可以在此了解两者差异.
快速入门:自定义工具
Toolbox 也可用作定制化工具的框架。
配置 Toolbox 的主要方式是通过 tools.yaml 文件。如果你有多个文件,可以使用 --config tools.yaml 标志指定 Toolbox 加载哪一个。
你可以在 Resources. 中找到所有资源类型的更详细参考文档。
Sources
tools.yaml 中的 sources 部分定义了 Toolbox 应能访问哪些数据源。大多数工具至少需要一个可执行的数据源。
kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password
有关配置不同类型数据源的更多详情,请参阅 Sources.
Tools
tools.yaml 中的 tools 部分定义了智能体可执行的操作:工具类型、影响的数据源、使用的参数等。
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 || '%';
有关如何配置不同类型工具的更多详情,请参阅 Tools.
Toolsets
你的 tools.yaml 中的 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
tools.yaml 中的 prompts 部分定义了可用于
与 LLM 交互的提示词(prompts)。
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"
有关如何配置提示词的更多详情,请参阅 Prompts.
安装并运行 Toolbox 服务器
你可以使用配置文件直接运行 Toolbox:
npx @toolbox-sdk/server --config tools.yaml
这会使用你的配置文件运行最新版本的 Toolbox 服务器。
Note
此方法优先考虑便利性,而非性能。 如需更标准、更可靠的安装方式,请使用二进制文件 或容器镜像,详见安装并运行 Toolbox 服务器。
安装 Toolbox
要获取最新版本,请查看 releases 页面,并按照 适用于你的操作系统和 CPU 架构的以下说明操作。
Binary
将 Toolbox 安装为二进制文件:
Linux (AMD64)
在 Linux (AMD64) 上将 Toolbox 安装为二进制文件:
# see releases page for other versions export VERSION=1.6.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox chmod +x toolboxmacOS (Apple Silicon)
在 macOS (Apple Silicon) 上将 Toolbox 安装为二进制文件:
# see releases page for other versions export VERSION=1.6.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox chmod +x toolboxmacOS (Intel)
在 macOS (Intel) 上将 Toolbox 安装为二进制文件:
# see releases page for other versions export VERSION=1.6.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/amd64/toolbox chmod +x toolboxWindows (Command Prompt)
在 Windows (Command Prompt) 上将 Toolbox 安装为二进制文件:
:: see releases page for other versions set VERSION=1.6.0 curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/amd64/toolbox.exe"Windows (PowerShell)
在 Windows (PowerShell) 上将 Toolbox 安装为二进制文件:
# see releases page for other versions $VERSION = "1.6.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/amd64/toolbox.exe"Windows ARM64 (Command Prompt)
在 Windows ARM64 (Command Prompt) 上将 Toolbox 安装为二进制文件:
:: see releases page for other versions set VERSION=1.6.0 curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/arm64/toolbox.exe"Windows ARM64 (PowerShell)
在 Windows ARM64 (PowerShell) 上将 Toolbox 安装为二进制文件:
# see releases page for other versions $VERSION = "1.6.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/arm64/toolbox.exe"
Container image
你也可以将 Toolbox 安装为容器:# see releases page for other versions
export VERSION=1.6.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
Homebrew
在 macOS 或 Linux 上使用 Homebrew 安装 Toolbox:
brew install mcp-toolbox
Compile from source
要从源码安装,请确保已安装最新版本的 Go,,然后运行以下命令:
go install github.com/googleapis/mcp-toolbox@v1.6.0
Gemini CLI
查看 [Gemini CLI extensions](https://geminicli.com/extensions/),可将针对 AlloyDB、BigQuery 和 Cloud SQL 等特定数据库的预构建工具直接安装到 Gemini CLI 中。# Install Gemini CLI
npm install -g @google/gemini-cli
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgres
# Run Gemini CLI
gemini
通过 Gemini CLI 使用自然语言与你的自定义工具交互。
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox
运行 Toolbox
配置一个 tools.yaml 来定义你的工具,然后
执行 toolbox 以启动服务器:
Binary
从二进制文件运行 Toolbox:
./toolbox --config "tools.yaml"
ⓘ Note
Toolbox 默认启用动态重载。要禁用此功能,请使用--disable-reload标志。
Container image
拉取容器镜像后运行服务器:
export VERSION=0.24.0 # Use the version you pulled
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"
ⓘ Note
-v标志会将你本地的tools.yaml挂载到容器中,-p会将 容器的端口5000映射到主机的端口5000。
Source
要直接从源码运行服务器,请进入项目根目录 并运行:
go run .
ⓘ Note
此命令从源码运行项目,更适合开发与 测试。它不会将二进制文件编译到你的$GOPATH中。如果你希望 改为编译二进制文件,请参阅开发者 文档。
Homebrew
如果你使用 Homebrew, 安装了 Toolbox,toolbox
二进制文件已在系统路径中可用。你可以使用相同的
命令启动服务器:
toolbox --config "tools.yaml"
NPM
无需手动下载二进制文件即可直接运行 Toolbox(需要 Node.js):
npx @toolbox-sdk/server --config tools.yaml
Gemini CLI
安装 [Gemini CLI extensions](https://geminicli.com/extensions/), 后,预构建工具将在使用时可用。# Run Gemini CLI
gemini
# List extensions
/extensions list
# List MCP servers
/mcp list
你可以使用 toolbox help 查看完整的标志列表!要停止服务器,请发送
终止信号(在大多数平台上为 ctrl+c)。
如需了解在不同环境中部署的更多详细文档,请查阅 Deploy Toolbox 章节 中的资源。
连接到 Toolbox
Toolbox 服务器启动并运行后,你可以将工具加载到兼容 MCP(Model Context Protocol)的客户端或应用中。
MCP 客户端
将以下配置添加到你的 MCP 客户端配置中:
{
"mcpServers": {
"toolbox": {
"type": "http",
"url": "http://127.0.0.1:5000/mcp",
}
}
}
如需连接到特定 toolset,请将 url 替换为 "http://127.0.0.1:5000/mcp/{toolset_name}"。
Toolbox SDK:与应用集成
Toolbox 客户端 SDK 提供了易于使用的构建模块和高级功能,用于将自定义应用连接到 MCP Toolbox 服务器。以下是适用于各种框架的客户端 SDK 列表:
Python (Github)
Core
安装 Toolbox Core SDK:
pip install toolbox-core加载工具:
from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name")有关 Toolbox Core SDK 的更多详细使用说明,请参阅 项目 README。
LangChain / LangGraph
pip install toolbox-langchain加载工具:
from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset()有关 Toolbox LangChain SDK 的更多详细使用说明,请参阅 项目 README。
LlamaIndex
pip install toolbox-llamaindex加载工具:
from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset()有关 Toolbox Llamaindex SDK 的更多详细使用说明,请参阅 项目 README。
Javascript/Typescript (Github)
Core
安装 Toolbox Core SDK:
npm install @toolbox-sdk/core加载工具:
import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const tools = await client.loadToolset('toolsetName');有关 Toolbox Core SDK 的更多详细使用说明,请参阅 项目 README。
LangChain / LangGraph
安装 Toolbox Core SDK:
npm install @toolbox-sdk/core加载工具:
import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool);Genkit
安装 Toolbox Core SDK:
npm install @toolbox-sdk/core加载工具:
import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [ googleAI({ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY }) ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool);ADK
安装 Toolbox ADK SDK:
npm install @toolbox-sdk/adk加载工具:
import { ToolboxClient } from '@toolbox-sdk/adk'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const tools = await client.loadToolset('toolsetName');有关 Toolbox ADK SDK 的更多详细使用说明,请参阅 项目 README。
Go (Github)
Core
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "github.com/googleapis/mcp-toolbox-sdk-go/core" "context" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000"; ctx := context.Background() client, err := core.NewToolboxClient(URL) // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) }有关 Toolbox Go SDK 更详细的使用说明,请参阅 [项目的 README][toolbox-core-go-readme]。
[toolbox-go]: https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core [toolbox-core-go-readme]: https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.mdLangChain Go
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "context" "encoding/json" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) // Fetch the tool's input schema inputschema, err := tool.InputSchema() var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } }Genkit
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "context" "log" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } log.Printf("Successfully converted tool: %s", genkitTool.Name()) }Go GenAI
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "context" "encoding/json" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) // Fetch the tool's input schema inputschema, err := tool.InputSchema() var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } }OpenAI Go
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "context" "encoding/json" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) // Fetch the tool's input schema inputschema, err := tool.InputSchema() var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } }ADK Go
安装 [Toolbox Go SDK][toolbox-go]:
go get github.com/googleapis/mcp-toolbox-sdk-go加载工具:
package main import ( "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "context" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } }有关 Toolbox Go SDK 更详细的使用说明,请参阅 [项目的 README][toolbox-core-go-readme]。
其他功能
使用 Toolbox UI 测试工具
要启动 Toolbox 的交互式 UI,请使用 --ui 标志。这使你能够测试
工具与 toolset,并支持授权参数等功能。要了解更多信息,
请访问 Toolbox UI.
./toolbox --ui
遥测(Telemetry)
Toolbox 通过 OpenTelemetry 发出追踪(trace)和指标(metric)。使用 --telemetry-otlp=<endpoint>
可导出到任何兼容 OTLP 的后端,例如 Google Cloud Monitoring、Agnost AI 或
其他服务。详情请参阅遥测文档。
生成 Agent Skill
skills-generate 命令允许你将 toolset 转换为符合 Agent Skill 规范. 的 Agent Skill。这对于将工具以可移植的 skill 包形式分发非常有用。
toolbox --config tools.yaml skills-generate \
--name "my-skill" \
--toolset "my_toolset" \
--description "A skill containing multiple tools"
生成后,你可以将该 skill 安装到 Gemini CLI:
gemini skills install ./skills/my-skill
更多详情,请参阅生成 Agent Skill 指南.。
版本控制
MCP Toolbox for Databases 遵循语义化版本(Semantic Versioning).。
公共 API 包括 Toolbox Server(CLI、配置清单和预构建 toolset)以及 Client SDK。
- 主版本(Major versions):当出现破坏性变更时递增,例如不兼容的 CLI 或清单变更。
- 次版本(Minor versions):在新增功能时递增,包括对预构建 toolset 或 beta 功能的修改。
- 补丁版本(Patch versions):在向后兼容的错误修复时递增。
更多详情,请参阅我们的完整版本控制政策.。
贡献
欢迎贡献。请参阅 CONTRIBUTING 指南以开始参与。
有关搭建 Toolbox 本身开发环境的技术细节,请参阅 DEVELOPER 指南。
请注意,本项目发布时附带贡献者行为准则(Contributor Code of Conduct)。参与本项目即表示您同意遵守其条款。更多信息请参阅 贡献者行为准则。
Community
加入我们的 Discord 社区,与我们的开发者建立联系!

