> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL 的 vsql_mcp 扩展

> vsql_mcp 扩展通过 Model Context Protocol 把 MySQL 提供给 AI 智能体，支持架构浏览、只读查询、表允许列表和行数上限。

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

| | |
| - | - |
| **维护者** | VillageSQL |
| **源代码和完整文档** | [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) |
| **许可证** | GPL-2.0 |
| **编写语言** | Rust |
| **能力** | 预览 |

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

## 安装

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

```sql theme={null}
INSTALL EXTENSION vsql_mcp;
```

确认它已存在：

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';
```

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

构建说明在[存储库](https://github.com/villagesql/vsql-mcp)中。

## 新增内容

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

```sql theme={null}
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` | 空闲的智能体会话保留多长时间，单位为秒 |

## 示例

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

```sql theme={null}
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`。
存储库提供了每种智能体的客户端配置。

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

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

## 另请参阅

* [通过 MCP 把 MySQL 提供给 AI 智能体](https://villagesql.com/docs/en/guides/mysql-ai-agents-mcp.md) — 连接智能体以及它能看到什么
* [管理扩展](https://villagesql.com/docs/zh/extensions/managing.md) — 扩展设置如何读取和写入
* [预览能力](https://villagesql.com/docs/zh/extensions/build/preview-capabilities.md) — 预览标志开启了什么，以及它承诺了什么
* [可用扩展](https://villagesql.com/docs/zh/extensions/catalog) — 完整目录
* [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) — 源代码、客户端设置和已知限制


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.