MCP Toolbox for Databases
官方专注于为数据库提供简单、快速且安全的工具的开源MCP服务器。
你可以用 Toolbox For Databases MCP 做什么?
- 即时探索数据库模式 — 使用预构建的工具如
list_tables来发现表和结构,无需编写 SQL。 - 通过自然语言运行临时 SQL 查询 — 让您的 AI 助手使用
execute_sql对连接的数据库执行查询。 - 定义自定义的参数化查询工具 — 创建一个
tools.yaml配置文件,其中包含接受参数并运行预定义语句的postgres-sql工具。 - 将工具分组为可加载的工具集 — 在配置中将相关工具组织到命名的工具集中,并仅加载特定代理所需的内容。
- 将工具集成到代理框架中 — 通过 Python、JS 或 Go SDK 将工具集加载到 LangChain、LlamaIndex、Genkit 或 ADK 应用程序中。
文档
MCP Toolbox for Databases 是一个开源的模型上下文协议(MCP)服务器,可将您的 AI 代理、IDE 和应用程序直接连接到您的企业数据库。
它服务于双重目的:
- 即用型 MCP 服务器(构建时): 使用我们的预构建通用工具,即时将 Gemini CLI、Google Antigravity、Claude Code、Codex 或其他 MCP 客户端连接到您的数据库。无需编写样板代码即可与数据对话、探索架构并生成代码。
- 自定义工具框架(运行时): 一个强大的框架,用于为您的生产代理构建专业化、高度安全的 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)。 - 自定义工具框架: 使用您自己的预定义逻辑构建生产级工具,通过受限访问、结构化查询和语义搜索确保安全性。
- 简化开发: 在不到 10 行代码内将工具集成到您的 Agent Development Kit (ADK)、LangChain、LlamaIndex 或自定义代理中。
- 更佳性能: 开箱即用地处理连接池、集成身份验证(IAM)和端到端可观测性(OpenTelemetry)。
- 增强安全性: 集成身份验证,更安全地访问您的数据。
- 端到端可观测性: 内置 OpenTelemetry 支持,提供开箱即用的指标和追踪。
快速入门:预构建工具
停止上下文切换,让您的 AI 助手成为真正的协作者。通过使用 MCP Toolbox 将您的 IDE 连接到数据库,您可以用自然语言查询数据、自动化架构发现和管理,并生成感知数据库的代码。
您可以在任何兼容 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 加载哪个文件。
您可以在资源中找到所有资源类型的更详细参考文档。
数据源
您的 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
有关配置不同类型数据源的更多详细信息,请参阅数据源。
工具
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.yaml 中的 toolsets 部分允许您定义要一起加载的工具组。这对于根据代理或应用程序定义不同组非常有用。
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
提示词
tools.yaml 中的 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"
有关配置提示词的更多详细信息,请参阅提示词。
安装并运行 Toolbox 服务器
您可以直接使用配置文件运行 Toolbox:
npx @toolbox-sdk/server --config tools.yaml
这将使用您的配置文件运行最新版本的 Toolbox 服务器。
[!NOTE] 此方法为方便而优化,而非性能。 如需更标准、更可靠的安装,请使用二进制文件或容器镜像,如安装并运行 Toolbox 服务器中所述。
安装 Toolbox
有关最新版本,请查看发布页面,并按照适用于您的操作系统和 CPU 架构的以下说明进行操作。
二进制文件
要将 Toolbox 安装为二进制文件:
Linux (AMD64)
要在 Linux (AMD64) 上将 Toolbox 安装为二进制文件:
# 查看发布页面获取其他版本 export VERSION=1.8.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 安装为二进制文件:
# 查看发布页面获取其他版本 export VERSION=1.8.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 安装为二进制文件:
# 查看发布页面获取其他版本 export VERSION=1.8.0 curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/amd64/toolbox chmod +x toolboxWindows(命令提示符)
要在 Windows(命令提示符)上将 Toolbox 安装为二进制文件:
:: 查看发布页面获取其他版本 set VERSION=1.8.0 curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/amd64/toolbox.exe"Windows (PowerShell)
要在 Windows (PowerShell) 上将 Toolbox 安装为二进制文件:
# 查看发布页面获取其他版本 $VERSION = "1.8.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/amd64/toolbox.exe"Windows ARM64(命令提示符)
要在 Windows ARM64(命令提示符)上将 Toolbox 安装为二进制文件:
:: 查看发布页面获取其他版本 set VERSION=1.8.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 安装为二进制文件:
# 查看发布页面获取其他版本 $VERSION = "1.8.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/arm64/toolbox.exe"
容器镜像
您也可以将 Toolbox 安装为容器:# see releases page for other versions
export VERSION=1.8.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
Homebrew
要在 macOS 或 Linux 上使用 Homebrew 安装 Toolbox:
brew install mcp-toolbox
Gemini CLI
查看 [Gemini CLI 扩展](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 启动服务器:
二进制文件
要从二进制文件运行 Toolbox:
./toolbox --config "tools.yaml"
ⓘ 注意
Toolbox 默认启用动态重载。要禁用,请使用--disable-reload标志。
容器镜像
拉取容器镜像后运行服务器:
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"
ⓘ 注意
-v标志将您的本地tools.yaml挂载到容器中,-p将 容器的5000端口映射到您主机的5000端口。
源码
要从源码直接运行服务器,请导航到项目根目录 并运行:
go run .
ⓘ 注意
此命令从源码运行项目,更适合开发和测试。它不会将二进制文件编译到您的$GOPATH中。如果您想 编译二进制文件,请参阅开发者 文档。
Homebrew
如果您使用 Homebrew 安装了 Toolbox,toolbox
二进制文件已在您的系统路径中。您可以使用相同的命令启动服务器:
toolbox --config "tools.yaml"
NPM
要直接运行 Toolbox 而不手动下载二进制文件(需要 Node.js):
npx @toolbox-sdk/server --config tools.yaml
Gemini CLI
安装 [Gemini CLI 扩展](https://geminicli.com/extensions/) 后,预构建的工具将在使用过程中可用。# Run Gemini CLI
gemini
# List extensions
/extensions list
# List MCP servers
/mcp list
您可以使用 toolbox help 查看完整的标志列表!要停止服务器,请发送
终止信号(在大多数平台上为 ctrl+c)。
有关部署到不同环境的更详细文档,请查看 https://mcp-toolbox.dev/documentation/deploy-to/ 中的资源。
连接到 Toolbox
一旦您的 Toolbox 服务器运行起来,您可以将工具加载到兼容 MCP 的客户端或 应用程序中。
MCP 客户端
将以下配置添加到您的 MCP 客户端配置中:
{
"mcpServers": {
"toolbox": {
"type": "http",
"url": "http://127.0.0.1:5000/mcp",
}
}
}
如果您想连接到特定的工具集,请将 url 替换为 "http://127.0.0.1:5000/mcp/{toolset_name}"。
Toolbox SDK:与您的应用程序集成
Toolbox 客户端 SDK 提供了易于使用的构建模块和高级功能,用于将您的自定义应用程序连接到 MCP Toolbox 服务器。以下是使用各种框架的客户端 SDK 列表:
Python (Github)
核心
安装 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)
核心
安装 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)
核心
安装 Toolbox Go SDK:
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。
LangChain Go
安装 Toolbox Go SDK:
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:
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:
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:
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:
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 UI 测试工具
要启动 Toolbox 的交互式 UI,请使用 --ui 标志。这允许您测试
工具和工具集,并支持授权参数等功能。要了解更多信息,请访问
Toolbox UI。
./toolbox --ui
遥测
Toolbox 通过 OpenTelemetry 发出追踪和指标。使用 --telemetry-otlp=<endpoint>
导出到任何兼容 OTLP 的后端,如 Google Cloud Monitoring、Agnost AI 或
其他。有关详细信息,请参阅 遥测文档。
生成代理技能
skills-generate 命令允许您将工具集转换为与 代理技能规范 兼容的代理技能。这对于将工具分发为可移植的技能包非常有用。
toolbox --config tools.yaml skills-generate \
--name "my-skill" \
--toolset "my_toolset" \
--description "A skill containing multiple tools"
生成后,您可以将技能安装到 Gemini CLI 中:
gemini skills install ./skills/my-skill
有关更多详细信息,请参阅 生成代理技能指南。
该仓库还附带现成的代理技能(例如维护者工作流)。请参阅 skills/ 查看目录和安装说明。
版本控制
MCP Toolbox for Databases 遵循 语义化版本控制。
公共 API 包括 Toolbox 服务器(CLI、配置清单和预构建的工具集)和客户端 SDK。
- 主版本 用于不兼容的更改,例如不兼容的 CLI 或清单更改。
- 次版本 用于新功能,包括对预构建工具集或测试版功能的修改。
- 修订版本 用于向后兼容的错误修复。
有关更多详细信息,请参阅我们的 完整版本控制政策。
贡献
欢迎贡献。请参阅 CONTRIBUTING 指南开始。
有关为 Toolbox 本身开发设置环境的技术细节,请参阅 DEVELOPER 指南。
请注意,本项目发布时附带贡献者行为准则。参与本项目即表示您同意遵守其条款。有关更多信息,请参阅 贡献者行为准则。
社区
加入我们的 Discord 社区 与我们的开发者联系!
