MCP Toolbox 连接指南通过官方 SDK、MCP 客户端、Gemini CLI 与 IDE 将数据库工具接入 AI 工作流【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxMCP Toolbox for Databases 是一款开源的 MCPModel Context Protocol服务器为数据库提供统一、可复用的 AI 工具层。当你完成服务器配置并成功运行后下一步就是把工具真正投入使用。本文基于仓库 connect-to 文档 的完整脉络系统讲解四类连接方式——官方 Client SDKPython / JavaScript / Go、MCP 兼容客户端与 CLI、Gemini CLI Extensions、IDE 集成并深入源码层面如 cmd/internal/flags.go 与 internal/server/mcp解释其底层原理。读完本文你将能够根据自身应用场景选择正确的接入路径并独立完成从终端到 IDE 的各类客户端配置。一、连接方式总览MCP Toolbox 如何作为通用控制平面因为 MCP Toolbox 构建在 Model Context ProtocolMCP之上它天然充当一个通用控制平面universal control plane可以被种类繁多的客户端消费——无论是代码中的应用、终端中的 CLI、还是你日常使用的 IDE。官方文档按使用场景将连接方式划分为三类Client SDKs应用集成面向需要构建自定义 AI Agent 或在代码中编排多步工作流的开发者。官方 SDK 允许应用在运行时动态获取工具 schema 并执行查询。MCP Clients CLIs面向不想编写完整应用的场景。你可以直接使用 MCP 兼容的命令行客户端与已配置的数据库交互并执行工具。IDE 集成把 Toolbox 直接接入 MCP 兼容的 IDE让 AI 编程助手实时访问数据库 schema从而写出精准匹配的查询与应用代码。此外Available Connection Methods一节提示一旦 Toolbox 服务器配置完成并运行选择哪种方式完全取决于你的使用场景。以下各节将逐一展开。二、方式一官方 Client SDKPython / JavaScript / Go2.1 SDK 能为你做什么Toolbox Client SDK 是连接自定义应用到 Toolbox 服务器的积木。无论你只是写一个执行单条查询的脚本还是在构建复杂的多 Agent 编排系统SDK 都会替你处理底层的 Model Context Protocol 通信让你专注于业务逻辑。具体来说SDK 负责从运行中的 Toolbox 实例获取工具定义提供代表这些工具的便捷 Python / JS / Go 对象或函数调用工具即调用 Toolbox 中配置的底层 API / 服务按需处理认证、参数绑定与安全参数Secure Parameters。官方对三种主流语言提供完整支持与框架深度集成详见 Toolbox SDKs 总览Python SDKs包含 Core SDK以及针对 LangChain、LlamaIndex 和 ADKAgent Development Kit的原生集成。JavaScript / TypeScript SDKs面向 Node.js 应用提供 Core SDK 与 ADK 集成。Go SDKs提供高并发友好的 Go Core SDK以及用于 Genkit 和 ADK 的集成包。2.2 Python 包选择用哪个包取决于你的编排框架以 Python SDK 文档 为例选包逻辑非常清晰包名适用场景兼容接口toolbox-adk使用 Google ADK 构建应用ADK 的BaseTool/BaseToolset自动处理认证传播、header 管理与工具包装toolbox-core不使用 LangChain/LangGraph 或任何编排框架框架无关适合自定义编排逻辑或纯脚本直接调用toolbox-langchain使用 LangChain / LangGraph 框架兼容 LangChain 的BaseTool接口toolbox-llamaindex使用 LlamaIndex 框架兼容 LlamaIndex 的BaseTool接口安装方式任选其一# 用于 Google ADK 集成 pip install google-adk[toolbox] # 或核心框架无关 SDK pip install toolbox-core # 或LangChain/LangGraph 集成 pip install toolbox-langchain # 或LlamaIndex 集成 pip install toolbox-llamaindex使用前需先按 本地快速上手 将主 MCP Toolbox 服务运行起来。2.3 跨 SDK 的 Secure Parameters 支持Secure Parameters安全参数允许开发者把敏感的、由应用控制的参数如租户 ID、会话令牌**带外out-of-band**直接传给工具完全隔离于 LLM 上下文与提示注入。各语言 SDK 的支持情况如下数据来自 SDK 总览语言 / SDK包名最低版本要求服务器要求Pythontoolbox-core、toolbox-adk、toolbox-langchain、toolbox-llamaindex前三个 1.4.0toolbox-llamaindex 0.9.0MCP2026-07-28com.google.cloud/toolbox.v1JavaScript / TypeScripttoolbox-sdk/core、toolbox-sdk/adk 1.2.0MCP2026-07-28com.google.cloud/toolbox.v1Gocore、tbadk、tbgenkitcore/tbadk v1.2.0tbgenkit v0.10.0MCP2026-07-28com.google.cloud/toolbox.v1三、方式二MCP 客户端与 CLI你并不需要构建完整应用才能使用 Toolbox。官方文档在 MCP Client 章节 中详细说明了如何从终端直接与数据库交互。3.1 先理解Toolbox SDK 与 MCP 的关系Toolbox 通过 Model Context Protocol 支持连接但它有若干不被 MCP 规范覆盖的特性例如Authenticated Parameters已认证参数要求每个调用附带已认证的属性如用户 ID、租户 ID 或请求 ID无法被注入到 LLM 上下文中的工具调用Authorized Invocation授权调用在工具执行前强制执行声明式 RBAC 权限检查检查基于调用者附带的已验证属性。官方建议优先使用原生 Toolbox Client SDK以充分利用这些特性同时 SDK 与 MCP 客户端在很多场景下可以组合使用。3.2 支持的 MCP 协议版本Toolbox 当前支持以下 MCP 规范版本2026-07-282025-11-252025-06-182025-03-262024-11-05对应到仓库源码这些版本分别在 internal/server/mcp 下的v20260728、v20251125、v20250618、v20250326、v20241105各目录中实现每个目录都包含 57 个协议实现文件。3.3 Secure Parameters 与 MCP 客户端的行为约定Secure Parameters 在 MCP 协议版本2026-07-28及更新版本上通过com.google.cloud/toolbox.v1扩展支持。仓库源码 internal/server/mcp/v20260728/extensions.go 与 manifests.go 印证了以下完整行为约定扩展协商MCP 客户端需在params._meta[io.modelcontextprotocol/clientCapabilities].extensions[com.google.cloud/toolbox.v1]中声明对该扩展的支持Manifeststools/list协商成功后工具会在inputSchema常规模型参数之外通过secureInputSchema定义应用控制的参数调用tools/call安全参数通过params.secureArguments带外传递模型生成的参数仍走params.arguments通用 MCP 客户端的降级行为未协商该扩展或使用2026-07-28之前协议版本的客户端其tools/list响应会自动过滤掉需要安全参数的工具。若仍直接调用则在协议2026-07-28上返回MissingRequiredClientCapabilityErrorJSON-RPC 错误码-32021在更早协议版本上返回ToolNotFoundError/INVALID_PARAMSJSON-RPC 错误码-32602tool does not exist因为安全工具在旧协议上完全不可见注入防御若客户端或模型尝试把安全参数塞进标准arguments服务器会拒绝该参数并返回工具执行错误isError: true。3.4 连接前置条件MCP 仅兼容 Toolbox0.3.0及以上版本。开始之前需要安装 Toolbox0.3.0参见安装说明中的 Installing the server 一节确保数据库已设置并初始化配置好 tools.yaml。3.5 通过 stdio 连接Toolbox 支持 MCP 的 stdio 传输协议使用 stdio 时必须携带--stdio标志./toolbox --stdio启用 stdio 后Toolbox 不再作为远程 HTTP 服务器而是通过标准输入输出监听日志默认设为warn级别stdio 模式下不支持debug与info日志Toolbox 默认启用动态重载dynamic reloading如需关闭请加--disable-reload标志。从源码看这些标志在 cmd/internal/flags.go 中定义--stdio对应Listens via MCP STDIO instead of acting as a remote HTTP server.--disable-reload对应Disables dynamic reloading of tools file.。动态重载在 cmd/root.go 中通过 fsnotify 文件监听器实现支持配置文件的 Write/Create/Rename 事件并带 100ms 防抖NFS 环境下可通过--poll-interval指定轮询秒数源码 cmd/root.go 的watchChanges函数。3.6 通过 HTTP 连接Toolbox 同时支持带 SSE 与不带 SSE 的 HTTP 传输协议。HTTP with SSE已弃用仅2024-11-05——MCP 客户端配置示例{ mcpServers: { toolbox: { type: sse, url: http://127.0.0.1:5000/mcp/sse } } }如需连接特定工具集toolset将url替换为http://127.0.0.1:5000/mcp/{toolset_name}/sse。Streamable HTTP推荐{ mcpServers: { toolbox: { type: http, url: http://127.0.0.1:5000/mcp } } }同理连接特定工具集时使用http://127.0.0.1:5000/mcp/{toolset_name}。这里的默认地址与端口127.0.0.1:5000对应源码中--address默认127.0.0.1与--port默认5000两个服务端标志见 cmd/internal/flags.go。3.7 使用 MCP Inspector 调试官方推荐使用 MCP Inspector 测试与调试 Toolbox 服务器三种传输方式均支持STDIO 模式npx modelcontextprotocol/inspector ./toolbox --stdio随后在 Inspector 界面Transport Type 选STDIOCommand 填./toolbox或二进制实际路径Arguments 填--stdio点击 Connect。HTTP with SSE已弃用先运行 Toolbox再单独执行npx modelcontextprotocol/inspectorTransport Type 选SSEURL 填http://127.0.0.1:5000/mcp/sse全部工具或http://127.0.0.1:5000/mcp/{toolset_name}/sse指定工具集。Streamable HTTP同样先运行 Toolbox 与npx modelcontextprotocol/inspectorTransport Type 选Streamable HTTPURL 填http://127.0.0.1:5000/mcp或http://127.0.0.1:5000/mcp/{toolset_name}。3.8 官方测试过的客户端根据官方文档的 Tested Clients 表以下客户端在 SSE 模式下验证可用客户端SSE 可用Claude Desktop✅MCP Inspector✅Cursor✅Windsurf✅VS Code (Insiders)✅四、方式三Gemini CLI ExtensionsGemini CLI 是一款开源 AI Agent用于辅助开发工作流编码、调试、数据探索、内容创作等其使命是为数据库与分析服务提供 agentic 交互界面。Gemini CLI 高度可扩展可通过 GitHub URL、本地目录或可配置的 registry 加载扩展扩展提供新的工具、斜杠命令slash commands与提示词prompts。以下是官方列出的一批由 MCP Toolbox 驱动的 Gemini CLI Extensions扩展代码托管于独立的 gemini-cli-extensions 仓库通过 URL 加载alloydb、alloydb-observabilitybigquery-conversational-analytics、bigquery-data-analyticscloud-sql-mysql、cloud-sql-mysql-observabilitycloud-sql-postgresql、cloud-sql-postgresql-observabilitycloud-sql-sqlserver、cloud-sql-sqlserver-observabilityknowledge-catalogfirestore-nativelookermcp-toolboxmysql、postgresspanner、sql-server加载这些扩展后即可直接在终端里用自然语言管理、查询你的数据。仓库中对应的预构建配置可在 internal/prebuiltconfigs/tools 目录下找到如alloydb-postgres.yaml、bigquery.yaml、cloud-sql-postgres.yaml等。五、方式四IDE 集成——以 PostgreSQL 为例将 Toolbox 直接接入 MCP 兼容 IDE 后AI 编程助手即可实时访问数据库 schema编写精准的查询与应用代码。仓库的 IDEs 章节 收录了面向 AlloyDB、BigQuery、Cloud SQL、Firestore、Looker、MSSQL、MySQL、Neo4j、Oracle、PostgreSQL、Spanner、SQLite 等多个数据库的接入指南。这里以 PostgreSQL using MCP 指南 为例演示完整流程该指南同样适用于 AlloyDB Omni。5.1 准备数据库创建或选择 PostgreSQL 实例本地安装 PostgreSQL或安装 AlloyDB Omni创建或复用数据库用户并准备好用户名与密码。5.2 安装 MCP Toolboxv0.6.0下载与操作系统、CPU 架构匹配的最新二进制按平台选择下载链接例如linux/amd64或darwin/arm64要求 Toolbox 版本V0.6.0当前文档示例版本为 v1.11.0赋予执行权限并验证chmod x toolbox ./toolbox --version5.3 配置 MCP 客户端各客户端配置的核心思路一致以 stdio 方式启动 toolbox使用--prebuilt postgres加载预构建的 PostgreSQL 工具配置并通过环境变量注入连接信息。以下配置在 Claude Code、Claude Desktop、Cline、Cursor、Windsurf、Gemini CLI、Gemini Code Assist 中结构相同仅存放位置与入口不同{ mcpServers: { postgres: { command: ./PATH/TO/toolbox, args: [--prebuilt, postgres, --stdio], env: { POSTGRES_HOST: , POSTGRES_PORT: , POSTGRES_DATABASE: , POSTGRES_USER: , POSTGRES_PASSWORD: } } } }各客户端的配置入口差异如下客户端配置文件位置 / 入口Claude Code项目根目录.mcp.json保存后重启 Claude CodeClaude DesktopSettings Developer Edit Config保存后重启ClineVS Code 扩展中 MCP Servers 图标 Configure MCP Servers连接成功显示绿色 active 状态Cursor项目根目录.cursor/mcp.json在 Settings Cursor Settings MCP 中查看状态VS Code (Copilot)项目根目录.vscode/mcp.json注意此处顶层键为servers而非mcpServersWindsurfCascade 助手中的锤子MCP图标 ConfigureGemini CLI / Gemini Code Assist工作目录下创建.gemini文件夹内含settings.json5.4 使用工具连接成功后你的 AI 工具即已通过 MCP 接入 PostgreSQL。可以尝试让 AI 助手列出表、创建表、定义并执行其他 SQL 语句。预构建的 PostgreSQL 工具集中LLM 可用的核心工具包括list_tables列出表及描述execute_sql执行任意 SQL 语句。注意预构建工具仍处于 pre-1.0 阶段工具可能在版本间变化由于 LLM 会自适应可用的工具这对大多数用户影响不大。六、连接方式选型建议与源码佐证综合官方文档与仓库源码可以给出如下选型建议构建自定义 Agent / 编排系统选择官方 Client SDKs。SDK 完整支持动态获取工具、绑定参数、带外安全参数、添加认证与运行时执行命令是唯一能完整利用 Authenticated Parameters 与 Authorized Invocation 等超集特性的路径终端快速交互选择 MCP Clientstdio 或 Streamable HTTP或 Gemini CLI Extensions无需编写应用即可使用自然语言查询数据IDE 内的 AI 编程助手选择 IDEs 接入指南让助手获得数据库 schema 的实时访问能力。从源码结构看cmd/root.go 是这一切连接的入口枢纽它注册了根命令及各子命令统一解析--stdio、--address、--port、--prebuilt、--disable-reload等标志stdio 模式走s.ServeStdioHTTP 模式走s.Listens.Serve。而 MCP 协议层的版本差异与安全参数扩展逻辑集中在 internal/server/mcp其中v20260728目录下的 extensions.go 与 manifests.go 正是上文 3.3 节行为约定的实现依据——这从侧面印证若你的客户端需要 Secure Parameters务必选择支持2026-07-28协议的 MCP 客户端或直接使用官方 SDK。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考