Fastmcp Mysql

FastMCP MySQL服务器

MySQL数据库操作的FastMCP服务器实现，为LLM应用程序提供对MySQL数据库的安全高效访问。

特性

• 🔒 缺省巩固安全：具有可选写入权限的只读访问
• ⚡ 高性能：连接池和异步操作
• 🛡️ SQL注入保护：内置查询验证和准备好的语句
• 📊 综合监控：结构化JSON日志记录
• 🔧 灵活的配置：基于环境变量的配置
• 🚀 轻松部署：安装并运行 uvx

安装

使用uvx（推荐）

# Run directly with uvx
uvx fastmcp-mysql

# With environment variables
MYSQL_HOST=localhost MYSQL_USER=myuser MYSQL_PASSWORD=mypass MYSQL_DB=mydb uvx fastmcp-mysql

使用pip

pip install fastmcp-mysql

来源

git clone https://github.com/jinto/fastmcp-mysql
cd fastmcp-mysql
uv sync --all-extras

配置

使用环境变量配置服务器：

必需变量

可选变量

用法

Claude桌面配置

使用Claude MCP CLI（推荐）

# Install from PyPI (when published)
claude mcp add fastmcp-mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="your_username" \
  -e MYSQL_PASSWORD="your_password" \
  -e MYSQL_DB="your_database" \
  -- uvx fastmcp-mysql

# Without specifying a database (use USE command)
claude mcp add fastmcp-mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_USER="your_username" \
  -e MYSQL_PASSWORD="your_password" \
  -- uvx fastmcp-mysql

# For local development
claude mcp add fastmcp-mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="your_username" \
  -e MYSQL_PASSWORD="your_password" \
  -e MYSQL_DB="your_database" \
  -- uv run --project /path/to/fastmcp-mysql fastmcp-mysql

手动配置

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["fastmcp-mysql"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DB": "your_database",
        "MYSQL_ENABLE_SECURITY": "true",
        "MYSQL_RATE_LIMIT_RPM": "60",
        "MYSQL_RATE_LIMIT_BURST": "10"
      }
    }
  }
}

可用工具

mysql_query

对配置的MySQL数据库执行SQL查询。

参数：

• query （string，必填）：要执行的SQL查询
• params （数组，可选）：查询已准备语句的参数
• database （字符串，可选）：目标数据库（用于多数据库模式）

例子：

# Simple query
result = await mysql_query("SELECT * FROM users WHERE active = 1")

# With parameters (SQL injection safe)
result = await mysql_query(
    "SELECT * FROM users WHERE age > %s AND city = %s",
    params=[18, "New York"]
)

# When no database is specified initially
result = await mysql_query("USE mydb")
result = await mysql_query("SHOW TABLES")
result = await mysql_query("SHOW DATABASES")

安全

默认安全功能

FastMCP MySQL包括全面的安全功能：

• 默认情况下为只读：必须显式启用写入操作
• SQL注入预防:

- SQL注入尝试的高级模式检测 - 所有查询的参数验证 - 检测编码的注入尝试（URL、Unicode、十六进制）

• 查询过滤:

- 黑名单模式：阻止危险操作（DDL、系统表、文件操作） - 白名单模式：只允许明确批准的查询模式 - 可定制的过滤规则

• 速率限制:

- 按用户请求限制 - 可配置算法（令牌桶、滑动窗口、固定窗口） - 突发保护

安全配置

通过环境变量配置安全功能：

启用写入操作

默认情况下，写入操作被禁用。谨慎启用它们：

# Enable specific write operations
MYSQL_ALLOW_INSERT=true \
MYSQL_ALLOW_UPDATE=true \
MYSQL_ALLOW_DELETE=true \
uvx fastmcp-mysql

安全最佳实践

1. 使用准备好的报表：始终使用参数而不是字符串连接
2. 最小特权原则：仅在必要时启用写入操作
3. 监控安全事件：检查日志中的安全违规行为
4. 速率限制：根据您的应用程序需求调整限制
5. 白名单模式：尽可能在生产环境中使用白名单模式

发展

设置开发环境

# Clone the repository
git clone https://github.com/jinto/fastmcp-mysql
cd fastmcp-mysql

# Create virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv sync --all-extras

# Install pre-commit hooks
pre-commit install

运行测试

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=fastmcp_mysql

# Run specific test file
uv run pytest tests/unit/test_query.py

# Run integration tests only
uv run pytest tests/integration/

代码质量

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests

# Type checking
uv run mypy src

建筑

服务器遵循清洁架构原则：

src/fastmcp_mysql/
├── __init__.py                 # Package initialization
├── __main__.py                 # Entry point for uvx
├── config.py                   # Configuration management
├── server.py                   # FastMCP server setup
├── connection.py               # Database connection management
├── security/                   # Security module (Clean Architecture)
│   ├── __init__.py
│   ├── manager.py              # Security orchestration
│   ├── config.py               # Security configuration
│   ├── exceptions.py           # Security exceptions
│   ├── interfaces/             # Abstract interfaces
│   │   ├── injection_detector.py
│   │   ├── query_filter.py
│   │   └── rate_limiter.py
│   ├── injection/              # SQL injection detection
│   │   ├── detector.py
│   │   └── patterns.py
│   ├── filtering/              # Query filtering
│   │   ├── blacklist.py
│   │   ├── whitelist.py
│   │   └── combined.py
│   └── rate_limiting/          # Rate limiting
│       ├── token_bucket.py
│       ├── sliding_window.py
│       ├── fixed_window.py
│       └── factory.py
└── tools/                      # MCP tools
    ├── __init__.py
    └── query.py                # Query execution tool

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

请确保：

• 所有测试均通过
• 代码格式为黑色
• 添加类型提示
• 文档已更新

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 基于 MCP服务器MySQL Node.js实现
• 内置于 FastMCP 框架
• MySQL连接通过 aiomysql文件

支持

• 📖 文档
• 🐛 问题追踪
• 💬 讨论