MySQL 的 vsql_mcp 扩展

vsql_mcp 通过 Model Context Protocol 把数据库提供给 AI 智能体，监听器位于服务器进程内部。智能体可以列出架构、描述表并运行只读查询。在您开启之前，写入始终关闭，并且查询路径通过您指定的数据库账户运行，因此智能体得到的正是您授予该账户的访问权限。


维护者	VillageSQL
源代码和完整文档	villagesql/vsql-mcp
许可证	GPL-2.0
编写语言	Rust
能力	预览

此扩展使用了四个预览能力，因此服务器必须以 --vsql_allow_preview_extensions=ON 启动。否则 INSTALL EXTENSION 会被拒绝。

安装

vsql_mcp 未随服务器捆绑，因此请先从存储库构建它，并把生成的 vsql_mcp.veb 复制到 veb_dir 系统变量所指定的目录中。然后安装它：

INSTALL EXTENSION vsql_mcp;

确认它已存在：

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';

+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_mcp       |
+----------------+

构建说明在存储库中。

新增内容

它添加了一个 SQL 函数 info()，用于报告监听器正在做什么。其余全部是配置和 MCP 流量。

SELECT CONVERT(info() USING utf8mb4) AS info;

{"enabled":false,"http_port":0,"https_port":0,"port":3100,"protocol_version":"2025-06-18","schema":"","sessions_active":0,"ssl_port":3143,"starting":false}

从 vsql_mcp.vsql_mcp_enabled 被设为 ON 的那一刻起，直到后台工作线程下一次唤醒（每 25 毫秒一次），starting 都是 true。在这个窗口内的调用也可能报告 "enabled":false，因为监听器尚未绑定。

设置	默认值	控制内容
`vsql_mcp.vsql_mcp_enabled`	`OFF`	监听器是否运行
`vsql_mcp.schema`	空	它提供的数据库
`vsql_mcp.db_url`	空	查询、写入和 explain 工具用来连接的账户
`vsql_mcp.allowed_tables`	空	这些工具可以访问哪些表
`vsql_mcp.allow_write`	`OFF`	写入工具是否存在
`vsql_mcp.max_rows`	`1000`	单个结果的行数上限
`vsql_mcp.query_timeout`	`30`	一条查询可以运行多长时间，单位为秒
`vsql_mcp.port`	`3100`	HTTP 端口
`vsql_mcp.ssl_port`	`3143`	HTTPS 端口
`vsql_mcp.ssl_cert`、`vsql_mcp.ssl_key`	空	HTTPS 的证书和密钥
`vsql_mcp.require_auth`	`OFF`	请求是否必须携带 bearer 令牌
`vsql_mcp.bearer_token`	空	该令牌
`vsql_mcp.session_ttl`	`1800`	空闲的智能体会话保留多长时间，单位为秒

示例

把监听器指向一个数据库并启动它：

SET GLOBAL vsql_mcp.schema = 'shop';
SET GLOBAL vsql_mcp.db_url = 'mysql://agent:secret@127.0.0.1:3306/shop';
SET GLOBAL vsql_mcp.allowed_tables = 'orders,customers';
SET GLOBAL vsql_mcp.vsql_mcp_enabled = ON;

然后智能体通过 MCP Streamable HTTP 连接到 http://127.0.0.1:3100。存储库提供了每种智能体的客户端配置。

db_url 中的账户决定了智能体能做什么的上限，而每个数据库账户都能用 SHOW VARIABLES 读到 db_url（包括密码），因此请只授予它所需的最小权限，并在确有需要之前保持 allow_write 关闭。在端口可以从 localhost 之外访问之前，请先开启 require_auth 并设置 bearer 令牌； SHOW VARIABLES 同样会把该令牌显示给每个账户。

用 SET PERSIST 写入的设置在重启后仍然保留，但 UNINSTALL EXTENSION 会删除它。卸载并重新安装后，每个设置都会恢复默认值，重启也不会恢复旧值。

另请参阅

通过 MCP 把 MySQL 提供给 AI 智能体 — 连接智能体以及它能看到什么
管理扩展 — 扩展设置如何读取和写入
预览能力 — 预览标志开启了什么，以及它承诺了什么
可用扩展 — 完整目录
villagesql/vsql-mcp — 源代码、客户端设置和已知限制

安装和运行扩展

扩展目录

构建扩展

安装

新增内容

示例

另请参阅

​安装

​新增内容

​示例

​另请参阅

安装

新增内容

示例

另请参阅