内容
# MCP MySQL / MariaDB
用于管理和操作 MySQL 和 MariaDB 数据库的 MCP（模型上下文协议）。通过 FastMCP 提供查询、分析、修改和连接配置工具。
## 需求
- Python 3.10+
- MySQL/MariaDB 服务器
- opencode（或任何 MCP 客户端）
### MySQL 连接器
**Windows / Linux / macOS**
```bash
pip install mysql-connector-python
```
## 安装
**1. 克隆仓库**
```bash
git clone <repo-url>
cd MCP_MYSQL
```
**2. 创建虚拟环境**
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate
# Linux
python3 -m venv .venv
source .venv/bin/activate
```
**3. 安装依赖**
```bash
pip install -r requirements.txt
```
## opencode 中的 MCP 配置
将以下内容添加到您的 opencode 配置文件（`opencode.json` 或 `~/.config/opencode/opencode.json`）中：
**Linux**
```json
{
"mcp": {
"mysql": {
"type": "local",
"enabled": true,
"command": [
"/full/path/to/MCP_MYSQL/.venv/bin/python",
"/full/path/to/MCP_MYSQL/Server.py"
]
}
}
}
```
**Windows**
```json
{
"mcp": {
"mysql": {
"type": "local",
"enabled": true,
"command": [
"C:\\full\\path\\to\\MCP_MYSQL\\.venv\\Scripts\\python.exe",
"C:\\full\\path\\to\\MCP_MYSQL\\Server.py"
]
}
}
}
```
## 入门（配置连接）
当 MCP 首次启动时，连接是空的。助手将引导您使用以下工具配置连接：
| 工具 | 参数 | 描述 |
|---|---|---|
| `configure_connection` | host, port, database, user, password, sql_repository | 一次设置所有参数 |
| `set_config` | host, port, database, user, password, sql_repository | 更新给定的字段（其他字段保持不变） |
| `get_config` | — | 显示当前配置（隐藏密码） |
| `test_connection` | database（可选） | 测试当前设置的连接 |
**典型流程：**
```
1. configure_connection(
host="localhost",
port="3306",
user="root",
password="my_password",
database="MyDB"
)
2. test_connection()
3. list_databases()
4. list_tables("MyDB")
5. describe_table("MyDB", "MyTable")
```
> 配置保存在 `config.json` 中。您可以在任何时候通过再次调用 `configure_connection` 或 `set_config` 更改主机或数据库。
## MCP 工具
### 配置
| 工具 | 参数 | 描述 |
|---|---|---|
| `get_config` | — | 显示当前配置（隐藏密码） |
| `set_config` | host, port, database, user, password, sql_repository | 更新 `config.json` 中的特定字段 |
| `configure_connection` | host, port, database, user, password, sql_repository | 一次设置所有连接参数 |
| `test_connection` | database（可选） | 使用当前配置测试连接 |
### 对象探索
| 工具 | 参数 | 描述 |
|---|---|---|
| `ping` | — | 检查 MySQL/MariaDB 连接性 |
| `list_databases` | — | 列出所有数据库 |
| `list_tables` | database | 列出数据库中的表 |
| `describe_table` | database, table | 列出表的列、类型、空值、默认值 |
| `list_procedures` | database | 列出存储过程 |
| `describe_procedure` | database, procedure | 显示存储过程的源代码和参数 |
| `list_functions` | database | 列出函数 |
| `describe_function` | database, function | 显示函数的源代码和参数 |
| `search_tables` | database, text | 按部分名称搜索表（LIKE） |
| `search_columns` | database, text | 按名称搜索列 |
| `search_procedures` | database, text | 按部分名称搜索存储过程 |
| `search_text` | database, text | 在存储过程/函数定义中搜索文本 |
| `list_foreign_keys` | database | 列出数据库中的所有外键 |
| `find_relationships` | database, table | 显示表的传入和传出关系 |
### 数据操作
| 工具 | 参数 | 描述 |
|---|---|---|
| `execute_query` | database, query | SELECT 或 CTE（只读并验证） |
| `execute_dml` | database, query, confirmed | INSERT/UPDATE/DELETE（需要 confirmed=True） |
| `execute_ddl` | database, sql_text, description | CREATE/ALTER（自动迁移） |
## 变更跟踪（日志和迁移）
每次运行 `execute_ddl`（CREATE/ALTER）时，系统会自动在 `sql_repository` 中保存完整的历史记录。您永远不会丢失任何修改记录。
### 保存了什么？
```
sql_repository/
└── MyDB/
├── Procedures/
│ └── MyProcedure/
│ └── Current.sql ← 当前定义及历史记录
├── Functions/
├── Views/
├── Tables/
├── Migrations/
│ └── Procedures/
│ └── 20260724_001_MyProcedure.sql ← 每次变更都是一个文件
└── Logs/
└── Changes.jsonl ← JSONL 格式的全审计日志
```
- **Current.sql**: 包含当前对象定义以及 `HISTORY` 块，记录所有以前的版本、日期、作者和每个变更的摘要。
- **Migrations/**: 每个 DDL 生成一个版本化的 SQL 文件（`YYYYMMDD_NNN_Name.sql`），包含确切的变更。您可以手动审查或回滚。
- **Logs/Changes.jsonl**: JSONL 格式的审计日志（每行一个变更），易于使用脚本处理或 grep 搜索。
### 为什么这很重要？
- 您可以随时恢复到任何对象的以前版本。
- 您确切地知道什么变更了、什么时候以及谁做的。
- 整个 `sql_repository` 可以在 Git 中版本控制，以实现端到端的追踪性。
