使用说明

MySQL MCP 服务器

一个用于MySQL数据库交互的模型上下文协议（MCP）服务器。该服务器使大型语言模型（LLMs）能够理解数据库架构，并利用内置的安全功能和可扩展性支持执行安全的SQL查询。

🚀 表情符号“🚀”在中文中通常被理解为“火箭”或“飞速前进”的意思，但直接翻译时，由于其本质是一个图形符号，没有固定的中文词汇对应，所以可以简单地描述为“火箭”或根据上下文意译为“飞速前进”、“加速”等。在没有具体上下文的情况下，最直接的翻译就是“火箭”。 快速入门刚接触这个项目？快来查看我们的入门指南为了最快地开始行动起来！

特性/功能

模式分析全面的数据库模式探索，包括表、视图和存储过程
安全查询执行内置SQL注入防护和只读查询验证
连接池高效的连接管理，支持可配置的连接池设置
Docker 支持带有多阶段构建的即用型Docker容器
TypeScript 支持完整的TypeScript实现，具备类型安全性
兼容AWS RDS针对支持SSL的AWS RDS MySQL实例进行了优化
可扩展架构设计用于高性能数据库交互

安装

本地开发

# Clone the repository
git clone https://github.com/Ahmustufa/mysql-mcp.git
cd mysql-mcp

# Install dependencies
npm install

# Install development dependencies (if not automatically installed)
npm install --save-dev tsx @types/node

Docker 安装

# Build the Docker image
docker build -t mysql-mcp .

# Or pull from registry (if published)
docker pull ahmustufa/mysql-mcp:latest

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required Database Configuration
DB_SERVER=localhost
DB_DATABASE=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password

# Optional Configuration
DB_PORT=3306
DB_SSL=false  # Set to 'false' to disable SSL, or leave undefined for AWS RDS SSL

# For AWS RDS MySQL
# DB_SERVER=your-rds-endpoint.region.rds.amazonaws.com
# DB_SSL=Amazon RDS  # Enables SSL for RDS

Docker 环境

对于Docker部署，您可以使用环境变量或一个 .env 文件：

# Docker with environment variables
docker run -e DB_SERVER=localhost \
           -e DB_DATABASE=mydb \
           -e DB_USER=user \
           -e DB_PASSWORD=password \
           mysql-mcp

# Docker with .env file
docker run --env-file .env mysql-mcp

使用方法

开发模式

npm run dev

生产模式

npm run build
npm start

Docker 使用

# Basic Docker run
docker run --env-file .env mysql-mcp

# Docker with port mapping (if extending with HTTP endpoints)
docker run -p 3000:3000 --env-file .env mysql-mcp

# Docker Compose (see docker-compose.yml section below)
docker-compose up -d

可用工具

1. 执行查询

执行带有内置安全验证的SQL查询。

参数：

query (字符串)：要执行的SQL查询

安全特性：

阻止破坏性操作（DROP、DELETE、TRUNCATE）
防止SQL注入攻击
以阅读为中心的操作（或：侧重于阅读的操作）

示例：

{
  "query": "SELECT * FROM users WHERE id = 1"
}

2. 列出表（或“显示表列表”）

列出当前数据库中的所有基表。

参数： 无

返回值： 包含模式、名称和类型的表格信息数组。

示例用法：

{
  "tool": "list_tables"
}

3. 描述表（或：表描述）

获取特定表的详细架构信息。

参数：

table_name (字符串)：要描述的表的名称

返回值： 列信息包括数据类型、可为空性、默认值和约束条件。

示例：

{
  "table_name": "users"
}

4. 获取表格数据

从表中检索示例数据。

参数：

table_name (字符串)：表的名称
limit （数字，可选）：要返回的行数（1-100，默认：10）

示例：

{
  "table_name": "users",
  "limit": 5
}

5. 主键（primary_keys）

获取特定表的主键列。

参数：

table_name (字符串)：表名

返回值： 指定表的主键列列表。

示例：

{
  "table_name": "users"
}

6. 搜索列（或：搜索字段）

查找列名与某个模式匹配的列（不区分大小写）。

参数：

like (字符串)：在列名中搜索的模式

返回值： 所有表中匹配列及其数据类型的列表。

示例：

{
  "like": "email"
}

7. 外键

列出表的外键关系。

参数：

table_name (字符串)：表名

返回： 该表既作为引用其他表的外键，也被其他表作为外键所引用。

示例：

{
  "table_name": "posts"
}

8. introspect_schema 翻译为中文是：“内省模式”或“自我反省模式”（具体翻译可能根据上下文有所调整，这里提供了一个较为通用的译法）

获取数据库的完整架构概览。

参数： 无

返回值： 所有表及其列、主键和外键关系的完整JSON映射。

示例：

{
  "tool": "introspect_schema"
}

安全特性

SQL注入防护高级模式检测与查询验证
只读默认值破坏性操作默认被阻止
连接池安全高效的数据库连接
SSL 支持内置SSL支持，用于安全的数据库连接
参数验证所有输入在执行前都会经过验证
查询长度限制防御DoS攻击

Docker 支持

基本的Docker命令

# Build the image
docker build -t mysql-mcp .

# Run with environment variables
docker run --rm \
  -e DB_SERVER=your-mysql-server \
  -e DB_DATABASE=your_database \
  -e DB_USER=your_user \
  -e DB_PASSWORD=your_password \
  mysql-mcp

# Run with .env file
docker run --rm --env-file .env mysql-mcp

# Run with volume mount for configuration
docker run --rm \
  -v $(pwd)/.env:/app/.env \
  mysql-mcp

Docker Compose

创建一个 docker-compose.yml 文件：

version: "3.8"

services:
  mysql-mcp:
    build: .
    environment:
      - DB_SERVER=mysql
      - DB_DATABASE=testdb
      - DB_USER=root
      - DB_PASSWORD=rootpassword
      - DB_PORT=3306
    depends_on:
      - mysql
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=testdb
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

volumes:
  mysql_data:

使用 Docker Compose 运行：

# Start services
docker-compose up -d

# View logs
docker-compose logs -f mysql-mcp

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

使用 Docker 进行扩展

对于高可用性部署：

version: "3.8"

services:
  mysql-mcp:
    build: .
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    environment:
      - DB_SERVER=mysql-primary
      - DB_DATABASE=proddb
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
    depends_on:
      - mysql-primary

  mysql-primary:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=proddb
    volumes:
      - mysql_primary_data:/var/lib/mysql
    deploy:
      placement:
        constraints: [node.role == manager]

volumes:
  mysql_primary_data:

错误处理

该服务器具备全面的错误处理功能：

数据库连接错误
查询验证错误
SQL执行错误
参数验证错误
优雅的关闭处理

数据库模式信息

服务器提供详细的模式信息，包括：

桌子列、数据类型、约束和结构
观点可用的数据库视图及其定义
数据类型MySQL特有的数据类型和约束
索引主键和索引信息
字符集UTF-8和排序规则支持

环境变量

变量	描述	默认值	是否必需
`DB_SERVER`	MySQL 服务器主机名或 IP	-	✅
`DB_DATABASE`	数据库名称	-	✅
`DB_USER`	数据库用户名	-	✅
`DB_PASSWORD`	数据库密码	-	✅
`DB_PORT`	数据库端口	3306	❌
`DB_SSL`	SSL 配置	'Amazon RDS'	❌

SSL 配置

设定；一套 DB_SSL=false 完全禁用SSL
未定义或设置为 'Amazon RDS' 用于支持AWS RDS的SSL
对于自定义SSL配置，请在代码中修改连接设置

AWS RDS 集成

此MCP服务器针对AWS RDS MySQL实例进行了优化：

# AWS RDS Configuration
DB_SERVER=your-rds-instance.region.rds.amazonaws.com
DB_DATABASE=your_database
DB_USER=admin
DB_PASSWORD=your_secure_password
DB_PORT=3306
# DB_SSL is automatically set to 'Amazon RDS' for SSL

RDS 安全组

确保您的RDS安全组允许来自应用程序的连接：

端口：3306（或您自定义的端口）
来源：您应用程序的IP范围或安全组

性能与可扩展性

连接池

服务器使用 MySQL2 内置的连接池：

自动连接管理
连接复用以提升性能
可配置的超时设置（默认60秒）

扩展策略

水平扩展部署多个MCP服务器实例
数据库读取副本针对读密集型工作负载，指向MySQL读取副本
连接限制监控并配置MySQL max_connections
资源监控使用CloudWatch或类似工具进行RDS监控

生产优化

# Multi-stage build for smaller production images
FROM node:22.20-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:22.20-alpine as production
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY build ./build
CMD ["node", "build/index.js"]

发展

项目结构

mysql-mcp/
├── src/
│   └── index.ts               # Main entry point with MCP server implementation
├── build/                     # Compiled TypeScript output
├── .env                       # Environment configuration
├── .dockerignore              # Docker ignore file
├── Dockerfile                 # Docker container configuration
├── docker-compose.yml         # Docker Compose setup (create this)
├── package.json              # Node.js dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This documentation

开发命令

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Watch for changes (compile only)
npm run watch

# Clean build directory
npm run clean

添加新工具

要添加新的MCP工具，请在其中注册它们 src/index.ts:

server.registerTool(
  "your_tool_name",
  {
    title: "Your Tool Title",
    description: "Description of what your tool does",
    inputSchema: {
      parameter: z.string().min(1),
    },
  },
  async ({ parameter }) => {
    // Your tool implementation
    const result = await performSomeOperation(parameter);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }
);

错误处理

服务器包含全面的错误处理机制：

数据库连接错误指数退避自动重试
查询验证错误无效查询的详细错误信息
SQL执行错误安全地报告错误，同时不泄露敏感数据
参数验证类型检查和数据净化
优雅地关闭正确清理数据库连接

故障排除

常见问题

连接被拒绝
```
Error: connect ECONNREFUSED
```
- 检查MySQL服务器是否正在运行
- 验证DB_SERVER和DB_PORT的配置
- 检查防火墙/安全组设置
认证失败
```
Error: Access denied for user
```
- 验证数据库用户名（DB_USER）和数据库密码（DB_PASSWORD）
- 检查MySQL中的用户权限
- 确保用户可以从您的主机连接
数据库未找到
```
Error: Unknown database
```
- 验证DB_DATABASE是否存在
- 检查用户是否有权限访问指定的数据库
SSL连接问题
```
Error: SSL connection error
```
- 对于本地开发：设置 DB_SSL=false
- 对于RDS：确保SSL证书已正确配置

调试模式

通过设置 NODE_ENV 来启用详细日志记录：

NODE_ENV=development npm run dev

测试

单元测试

# Add testing framework
npm install --save-dev jest @types/jest

# Run tests
npm test

集成测试

# Test with actual database
npm run test:integration

负载测试

# Test connection pooling and performance
npm run test:load

贡献

我们欢迎投稿！请遵循以下指南：

入门指南/开始使用

为仓库创建分支（或“克隆仓库”）
创建一个特性分支： git checkout -b feature/your-feature-name
使用适当的 TypeScript 类型进行修改
为新功能添加测试
根据需要更新文档
提交一个拉取请求

代码风格

为所有新代码使用TypeScript
遵循 ESLint 和 Prettier 的配置
为公共API添加JSDoc注释
使用语义化的提交信息

拉取请求流程

确保所有测试都通过
如有需要，请更新README文件
添加对更改的清晰描述
提及任何相关问题

更新日志

版本1.1.0

从MSSQL切换到MySQL支持
增加了AWS RDS SSL兼容性
改进的连接池
增加了对多阶段构建的Docker支持
通过查询验证增强安全性

版本1.0.0

首次发布，包含基本MCP工具
TypeScript 实现
基本的Docker支持

许可证

Apache许可证2.0版 - 详见许可证文件中有详细信息。

支持

对于问题和疑问：

GitHub Issues（GitHub问题）: 打开一个问题（或：提交一个问题）
文档请查阅此README文件以获取常见解决方案
社区参与GitHub讨论区的讨论

致谢

优秀SDK的模型上下文协议团队
MySQL2 的维护者们，负责这个强大的数据库驱动
开源社区助力持续改进

使用说明

MySQL MCP 服务器

特性/功能

安装

本地开发

Docker 安装

配置

环境变量

Docker 环境

使用方法

开发模式

生产模式

Docker 使用

可用工具

1. 执行查询

2. 列出表（或“显示表列表”）

3. 描述表（或：表描述）

4. 获取表格数据

5. 主键（primary_keys）

6. 搜索列（或：搜索字段）

7. 外键

8. introspect_schema 翻译为中文是：“内省模式”或“自我反省模式”（具体翻译可能根据上下文有所调整，这里提供了一个较为通用的译法）

安全特性

Docker 支持

基本的Docker命令

Docker Compose

使用 Docker 进行扩展

错误处理

数据库模式信息

环境变量

SSL 配置

AWS RDS 集成

RDS 安全组

性能与可扩展性

连接池

扩展策略

生产优化

发展

项目结构

开发命令

添加新工具

错误处理

故障排除

常见问题

调试模式

测试

单元测试

集成测试

负载测试

贡献

入门指南/开始使用

代码风格

拉取请求流程

更新日志

版本1.1.0

版本1.0.0

许可证

支持

相关项目

致谢

相关 MCP

DuckDB数据库交互服务

GraphQL模式分析工具

Oracle数据库MCP服务器

PostgreSQL数据库交互服务

MySQL数据库访问服务

漏洞查询服务