MySQL Navigator MCP

一个强大的 MySQL/MariaDB 数据库导航工具，使用 MCP（Model Control Protocol）进行简便的数据库查询和管理。

功能

• 连接到 MySQL/MariaDB 数据库
• 动态切换不同的数据库
• 执行类型安全的 SQL 查询
• 获取数据库模式信息
• 使用 Pydantic 模型验证查询参数
• 安全的凭证管理
• 全面的日志系统
• 连接池和重试机制
• 支持 SSL/TLS 的安全连接

日志文件位置（跨平台）

默认情况下，所有日志都写入到：

• Windows: C:Users<YourUsername>.mcpmcp-db.log
• macOS/Linux: /home/<yourusername>/.mcp/mcp-db.log 或 /Users/<yourusername>/.mcp/mcp-db.log

如果您的主目录中不存在 .mcp 文件夹，应用程序将自动创建它。如果您遇到任何问题，可以手动创建该文件夹：

Windows:
powershell
mkdir $env:USERPROFILE.mcp

macOS/Linux:
bash
mkdir -p ~/.mcp

安装

从 PyPI（推荐大多数用户使用）:

bash
pip install mcp-db-navigator

从源代码安装（用于开发）:

bash
git clone
cd mcp-db
pip install -e .

1. 创建一个包含数据库凭据的 .env 文件：
   env
   DB_HOST=your_host
   DB_PORT=your_port
   DB_NAME=your_database_name
   DB_USER=your_username
   DB_PASSWORD=your_password
   DB_SSL_CA=/path/to/ssl/ca.pem # 可选：用于 SSL/TLS 连接
   DB_MAX_RETRIES=3 # 可选：连接重试次数
   DB_RETRY_DELAY=1.0 # 可选：重试之间的延迟时间（秒）

使用示例

1. 命令行

直接从终端运行 MCP 服务器：
bash
mcp-db --config /path/to/your/project/.env

2. 在 Cursor 中

要在 Cursor 中使用此 MCP 服务器：

• 打开 Cursor 设置并添加一个新的 MCP 服务器。
• 使用以下配置（示例）：

json
{
"mcpServers": {
"mysql-navigator": {
"command": "mcp-db",
"args": [
"--config",
"/absolute/path/to/your/.env"
]
}
}
}

• 确保您的 .env 文件路径是绝对路径。

3. 在 Claude Desktop 中

如果 Claude Desktop 支持 MCP 服务器：

• 添加一个新的 MCP 服务器，并将其指向带有 --config 参数的 mcp-db 命令。
• 有关添加自定义 MCP 服务器的详细信息，请参阅 Claude Desktop 的文档。

查询参数

查询字典支持以下参数：

• table_name（必需）：要查询的表名
• select_fields（可选）：要选择的字段列表（默认为 ["*"]）
• where_conditions（可选）：WHERE 子句的字段-值对字典
• order_by（可选）：排序字段列表
• order_direction（可选）：排序方向 "ASC" 或 "DESC"（默认："ASC"）
• limit（可选）：返回的记录数
• offset（可选）：跳过的记录数
• group_by（可选）：分组字段列表
• having（可选）：HAVING 子句的字段-值对字典
• join_table（可选）：要连接的表名
• join_type（可选）：JOIN 操作类型（默认："INNER"）
• join_conditions（可选）：JOIN 条件字典

安全特性

• 通过配置文件管理数据库凭据
• 密码以 SecretStr 形式存储在 Pydantic 模型中
• 对所有查询参数进行输入验证
• 通过参数化查询防止 SQL 注入
• 支持 SSL/TLS 加密连接
• 连接字符串清理
• 查询速率限制
• 查询参数清理

生产特性

错误处理

• 对数据库操作进行全面的错误处理
• 连接超时处理
• 自动重试机制以应对失败的连接
• 对所有参数进行输入验证

性能

• 通过连接池优化资源使用
• 记录查询执行时间
• 连接池统计信息
• 收集性能指标

监控- 结构化日志记录，支持不同日志级别

• 查询执行跟踪
• 连接状态监控
• 错误率跟踪

贡献代码

1. Fork 仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。