使用说明

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

配置

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

必需变量

变量	描述	默认值
`MYSQL_USER`	数据库用户名	-
`MYSQL_PASSWORD`	数据库密码	-

可选变量

变量	描述	默认值
`MYSQL_HOST`	数据库主机	“127.0.0.1”
`MYSQL_PORT`	数据库端口	“3306”
`MYSQL_DB`	数据库名称（可选）	无
`MYSQL_ALLOW_INSERT`	启用INSERT查询	false
`MYSQL_ALLOW_UPDATE`	启用UPDATE查询	false
`MYSQL_ALLOW_DELETE`	启用DELETE查询	false
`MYSQL_POOL_SIZE`	连接池大小	10
`MYSQL_QUERY_TIMEOUT`	查询超时（毫秒）	30000
`MYSQL_LOG_LEVEL`	日志级别（调试、信息、警告、错误）	信息
`MYSQL_CACHE_ENABLED`	启用查询结果缓存	true
`MYSQL_CACHE_MAX_SIZE`	最大缓存条目数	1000
`MYSQL_CACHE_TTL`	缓存TTL（毫秒）	60000
`MYSQL_CACHE_EVICTION_POLICY`	缓存驱逐策略（lru/ttl/fifo）	lru
`MYSQL_CACHE_CLEANUP_INTERVAL`	缓存清理间隔（秒）	60.0
`MYSQL_CACHE_INVALIDATION_MODE`	缓存失效策略	激进
`MYSQL_STREAMING_CHUNK_SIZE`	流式查询块大小	1000
`MYSQL_PAGINATION_DEFAULT_SIZE`	默认页面大小	10
`MYSQL_PAGINATION_MAX_SIZE`	最大页面大小	1000

用法

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、系统表、文件操作）
- 白名单模式：只允许明确批准的查询模式
- 可定制的过滤规则
速率限制:
- 按用户请求限制
- 可配置算法（令牌桶、滑动窗口、固定窗口）
- 突发保护

安全配置

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

变量	描述	默认值
`MYSQL_ENABLE_SECURITY`	启用所有安全功能	true
`MYSQL_ENABLE_INJECTION_DETECTION`	启用SQL注入检测	true
`MYSQL_ENABLE_RATE_LIMITING`	启用速率限制	true
`MYSQL_FILTER_MODE`	过滤模式（黑名单/白名单/组合）	黑名单
`MYSQL_RATE_LIMIT_RPM`	每分钟请求速率限制	60
`MYSQL_RATE_LIMIT_BURST`	速率限制的突发大小	10
`MYSQL_RATE_LIMIT_ALGORITHM`	速率限制算法（token_bucket/sliding_indow/fixed_window）	token_backet
`MYSQL_MAX_QUERY_LENGTH`	最大查询长度（字符）	10000
`MYSQL_MAX_PARAMETER_LENGTH`	最大参数长度	1000
`MYSQL_LOG_SECURITY_EVENTS`	日志安全违规	true
`MYSQL_LOG_REJECTED_QUERIES`	记录被拒绝的查询	true
`MYSQL_AUDIT_ALL_QUERIES`	审核所有查询（性能影响）	false

启用写入操作

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

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

安全最佳实践

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

发展

设置开发环境

# 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

贡献

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

请确保：

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

许可证

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

致谢

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

支持

📖 文档
🐛 问题追踪
💬 讨论