使用说明

MySQL MCP Server

一个 Model Context Protocol (MCP) 服务器，使 AI 代理能够安全地查询 MySQL 数据库。支持 MySQL、MariaDB、AWS Aurora MySQL 以及其他 MySQL 兼容数据库。作为Quick Suite的action，集成MCP能力给chatagent。

功能特性

只读访问：仅允许 SELECT、SHOW、DESCRIBE、EXPLAIN 和 WITH 查询
多种工具：查询执行、表列表、模式检查和数据库发现
类型安全：正确处理 NULL 值、日期和二进制数据
AWS AgentCore 部署：直接部署 Python 代码，无需 Docker
完整日志：跟踪查询执行、错误和性能
安全优先：OAuth 认证和查询验证

可用的 MCP 工具

1. `query`

对数据库执行 SELECT 查询。

参数：

sql (字符串，必需)：要执行的 SQL 查询

返回：

columns：列名列表
rows：行对象数组
row_count：返回的行数

2. `list_tables`

列出已连接数据库中的所有表。

返回：

tables：表名数组

3. `describe_table`

获取表的详细模式信息。

参数：

table_name (字符串，必需)：要描述的表名

返回：

table_name：表名
columns：列信息数组（名称、类型、可空性、默认值、键、额外信息）
primary_keys：主键列名数组
foreign_keys：外键关系数组

4. `list_databases`

列出 MySQL 实例上所有可访问的数据库。

返回：

databases：数据库名数组

前置要求

具有适当权限的 AWS 账户
已配置 AWS CLI
Python 3.10+ 和 pip
MySQL、MariaDB 或 Aurora MySQL 数据库
Bedrock AgentCore Starter Toolkit

快速开始

步骤 1：安装部署工具

# 创建虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 Windows: .venv\Scripts\activate

# 安装 AgentCore 工具
pip install bedrock-agentcore-starter-toolkit

步骤 2：设置 Cognito 认证

运行脚本创建 Service-to-Service 认证配置：

chmod +x setup_s2s_cognito.sh
./setup_s2s_cognito.sh us-east-1

脚本将自动：

创建 Cognito User Pool 和 Domain
创建 Resource Server 和 App Client
生成 OAuth Discovery URL 和 Client ID
保存配置到 .cognito-s2.env 文件

记录输出中的关键信息：

OAuth Discovery URL：https://cognito-idp.{region}.amazonaws.com/{pool-id}/.well-known/openid-configuration
Client ID：用于 OAuth 认证

步骤 3：配置 AgentCore

进入 src 目录并运行配置命令：

cd src
agentcore configure -e mysql_mcp_server.py --protocol mcp

按照提示配置：

Agent Name：输入名称（如 mysql_mcp_server_01）或按 Enter 使用默认值
Requirements File：按 Enter 使用检测到的 requirements.txt
Deployment Type：选择 1 (Direct Code Deploy - 推荐)
Python Runtime：选择 3 (Python 3.12)
Execution Role：按 Enter 自动创建
S3 Bucket：按 Enter 自动创建
OAuth Configuration：
- 输入 yes 启用 OAuth
- 粘贴步骤 2 中的 OAuth Discovery URL
- 粘贴步骤 2 中的 Client ID
Request Header Allowlist：按 Enter 使用默认配置
Memory Configuration：输入 s 跳过

配置完成后，会在 src 目录生成 .bedrock_agentcore.yaml 文件。

步骤 4：配置数据库环境变量

在项目根目录创建 .env 文件：

cp .env.example .env

编辑 .env 文件，填入数据库连接信息：

DB_HOST=your-mysql-host.rds.amazonaws.com
DB_USER=your_username
DB_NAME=your_database
DB_PASSWORD=your_password
DB_PORT=3306
LOG_LEVEL=INFO

必需的环境变量：

DB_HOST：MySQL 服务器地址
DB_USER：数据库用户名
DB_NAME：数据库名称
DB_PASSWORD：数据库密码

可选的环境变量：

DB_PORT：数据库端口（默认 3306）
LOG_LEVEL：日志级别（默认 INFO）

步骤 5：部署到 AWS

方式一：使用辅助脚本（推荐）

使用提供的脚本自动从 .env 文件加载环境变量：

./launch_with_env.sh

方式二：手动指定环境变量

进入 src 目录并手动传递环境变量：

cd src
agentcore launch \
  --env DB_HOST=your-mysql-host.rds.amazonaws.com \
  --env DB_USER=your_username \
  --env DB_NAME=your_database \
  --env DB_PASSWORD=your_password \
  --env DB_PORT=3306 \
  --env LOG_LEVEL=INFO

部署过程将：

自动创建 IAM Execution Role 和 S3 Bucket
构建依赖包（使用 uv 进行跨平台编译）
打包源代码并上传到 S3
创建 AgentCore Runtime
配置 CloudWatch 日志和 X-Ray 追踪

部署成功后，记录输出中的 Agent ARN：

arn:aws:bedrock-agentcore:us-east-1:ACCOUNT_ID:runtime/mysql_mcp_server_01-xxxxx

步骤 6：测试部署

6.1 获取 Bearer Token

返回项目根目录，运行脚本获取访问令牌：

cd ..
./test-s2s-token.sh

复制输出中的 Access Token。

6.2 设置环境变量并测试

export AGENT_ARN="arn:aws:bedrock-agentcore:us-east-1:ACCOUNT_ID:runtime/mysql_mcp_server_01-xxxxx"
export BEARER_TOKEN="eyJraWQiOiJ..."

python test_agentcore_remote.py

测试脚本将：

列出所有可用的 MCP 工具
执行 list_databases 查询
执行 list_tables 查询
执行示例 SQL 查询

成功输出示例：

Available tools: ['query', 'list_tables', 'describe_table', 'list_databases']

使用示例

查询执行

# 执行 SELECT 查询
result = query(sql="SELECT * FROM users WHERE active = 1 LIMIT 10")

# 结果格式：
{
    "columns": ["id", "name", "email", "created_at"],
    "rows": [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01T00:00:00"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-01-02T00:00:00"}
    ],
    "row_count": 2
}

模式发现

# 列出所有表
tables = list_tables()
# 返回：{"tables": ["users", "orders", "products"]}

# 描述表
schema = describe_table(table_name="users")
# 返回包含列、主键和外键的详细模式

# 列出所有数据库
databases = list_databases()
# 返回：{"databases": ["mysql", "information_schema", "myapp"]}

错误处理

# 危险查询（被拒绝）
result = query(sql="DELETE FROM users")
# 返回：{"error": "Operation DELETE is not allowed"}

# 语法错误
result = query(sql="SELECT * FORM users")
# 返回：{"error": "You have an error in your SQL syntax..."}

# 不存在的表
schema = describe_table(table_name="nonexistent")
# 返回：{"error": "Table 'nonexistent' not found"}

监控和日志

CloudWatch 日志

查看运行时日志：

# 实时查看日志
aws logs tail /aws/bedrock-agentcore/runtimes/mysql_mcp_server_01-xxxxx-DEFAULT \
  --log-stream-name-prefix "2025/12/01/[runtime-logs" \
  --follow

# 查看最近 1 小时的日志
aws logs tail /aws/bedrock-agentcore/runtimes/mysql_mcp_server_01-xxxxx-DEFAULT \
  --log-stream-name-prefix "2025/12/01/[runtime-logs" \
  --since 1h

GenAI Observability Dashboard

访问 CloudWatch GenAI Observability Dashboard 查看：

请求量和延迟
错误率和类型
X-Ray 追踪信息

Dashboard URL：

https://console.aws.amazon.com/cloudwatch/home?region=us-east-1#gen-ai-observability/agent-core

安全考虑

查询限制

仅允许只读查询：

✅ SELECT、SHOW、DESCRIBE、EXPLAIN、WITH
❌ INSERT、UPDATE、DELETE、DROP、CREATE、ALTER、TRUNCATE、GRANT、REVOKE

凭证保护

密码永远不会被记录或在错误消息中暴露
使用环境变量存储敏感配置
考虑为 Aurora MySQL 使用 IAM 认证

最佳实践

最小权限原则：仅授予数据库用户 SELECT 权限
网络安全：使用 VPC 和安全组限制访问
SSL/TLS：在生产环境中启用加密连接
监控：定期检查日志以发现可疑活动
速率限制：为生产部署实施速率限制

故障排除

连接问题

问题："Failed to connect to database"

解决方案：

验证 DB_HOST、DB_USER、DB_PASSWORD 和 DB_NAME 是否正确
检查到数据库的网络连接
确保数据库用户具有适当的权限
验证防火墙/安全组规则允许连接

查询失败

问题："Operation X is not allowed"

解决方案：仅允许只读查询。使用 SELECT 而不是 INSERT/UPDATE/DELETE。

问题："Table 'X' not found"

解决方案：

验证表名拼写是否正确（某些系统区分大小写）
确保连接到正确的数据库
检查用户是否有权限访问该表

部署问题

问题：AgentCore 部署失败

解决方案：

验证 AWS 凭证配置是否正确
检查 IAM 角色是否具有必要的权限
确保 S3 bucket 可访问
查看 CloudWatch 日志以获取详细错误消息

认证问题

问题："Unauthorized" 或 "Invalid token"

解决方案：

使用 ./test-s2s-token.sh 重新生成 Bearer Token
确认 OAuth Discovery URL 和 Client ID 配置正确
检查 token 是否已过期（默认 1 小时有效期）

在 Amazon Quick Suite 中配置 Action

部署完成后，在 Quick Suite 中将 MCP Server 配置为 Action。

配置步骤

选择 Action 类型，然后选择 MCP Server

填写基本信息：
- Integration name：如 MySQL MCP Server
- Description：可选

配置连接信息：
- Agent ARN：步骤 5 中部署获得的 ARN
- Authentication type：选择 OAuth 2.0 (Service-to-Service)
- OAuth Discovery URL：步骤 2 中的 Discovery URL
- Client ID 和 Client Secret：从 .cognito-s2.env 获取
```
cat .cognito-s2.env | grep CLIENT_SECRET
```

点击 Create integration，系统会自动发现可用工具（query、list_tables、describe_table、list_databases）

在应用中使用

在 Quick Suite 应用的 Actions 配置中选择此 Integration，AI 即可查询 MySQL 数据库：

"列出所有表" → list_tables
"查询 users 表前 10 条记录" → query
"描述 orders 表结构" → describe_table

VPC 配置（可选）

如果 MySQL 数据库位于 VPC 内，需要配置 AgentCore Runtime 的网络设置以访问 VPC 资源。

配置步骤

打开 AWS 控制台，导航到 Bedrock AgentCore
找到已部署的 Runtime（使用步骤 5 中的 Agent ARN）
进入 Runtime 详情页面，点击"编辑"
在"高级设置"中配置网络：
- VPC：选择 MySQL 所在的 VPC
- 子网：选择至少 2 个不同可用区的私有子网
- 安全组：选择允许访问 MySQL 的安全组
保存配置

安全组要求

确保选择的安全组允许：

出站规则：允许访问 MySQL 端口（默认 3306）到数据库安全组
入站规则：数据库安全组需要允许来自 AgentCore 安全组的连接

注意事项

VPC 配置后，Runtime 将无法访问公网资源（除非配置 NAT Gateway）
配置变更后，Runtime 会自动重启
首次配置可能需要几分钟生效

清理资源

删除所有创建的 AWS 资源：

# 删除 AgentCore Runtime
agentcore delete

# 删除 Cognito 资源
./cleanup-cognito-s2s.sh

项目结构

mysql-mcp/
├── src/
│   ├── mysql_mcp_server.py      # MCP 服务器主实现
│   ├── requirements.txt          # Python 依赖
│   └── .bedrock_agentcore.yaml   # AgentCore 配置（生成）
├── tests/
│   └── test_properties.py        # 基于属性的测试
├── setup_s2s_cognito.sh          # Cognito 设置脚本
├── test-s2s-token.sh             # Token 获取脚本（生成）
├── cleanup-cognito-s2s.sh        # 资源清理脚本（生成）
├── test_agentcore_remote.py      # 远程测试脚本
├── .cognito-s2.env               # Cognito 配置（生成）
├── .env.example                  # 环境变量模板
└── README.md                     # 本文件

许可证

MIT License

支持

如有问题、疑问或贡献，请提交 Issue 或 Pull Request。

使用说明

MySQL MCP Server

功能特性

可用的 MCP 工具

1. query

2. list_tables

3. describe_table

4. list_databases

前置要求

快速开始

步骤 1：安装部署工具

步骤 2：设置 Cognito 认证

步骤 3：配置 AgentCore

步骤 4：配置数据库环境变量

步骤 5：部署到 AWS

方式一：使用辅助脚本（推荐）

方式二：手动指定环境变量

步骤 6：测试部署

6.1 获取 Bearer Token

6.2 设置环境变量并测试

使用示例

查询执行

模式发现

错误处理

监控和日志

CloudWatch 日志

GenAI Observability Dashboard

安全考虑

查询限制

凭证保护

最佳实践

故障排除

连接问题

查询失败

部署问题

认证问题

在 Amazon Quick Suite 中配置 Action

配置步骤

在应用中使用

VPC 配置（可选）

配置步骤

安全组要求

注意事项

清理资源

项目结构

许可证

支持

相关 MCP

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Claude Code开发工具包

区块链交互服务器

语言服务器协议模型上下文协议

1. `query`

2. `list_tables`

3. `describe_table`

4. `list_databases`