🚀 阿里云操作 MCP 服务器
这是一个用于 Amazon Q CLI 的阿里云操作 MCP 服务器，支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 等服务，可助力用户更便捷地管理阿里云相关资源。
English | 中文
🚀 快速开始
系统要求
- Python 3.10+ (通过 uv 自动管理)
- uv - Python 包和项目管理器
- 阿里云访问凭证
操作步骤
1. 安装 uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 pip
pip install uv
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. 克隆项目
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp
3. 一键安装
# 运行安装脚本（推荐）
./install.sh
# 或者手动安装
uv sync
cp .env.example .env
# 编辑 .env 文件，填入你的阿里云凭证
4. 配置环境变量
编辑 .env 文件：
ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
ALIBABA_CLOUD_REGION="cn-beijing"
5. 验证安装
# 运行验证脚本
uv run python verify_setup.py
# 测试服务器启动
uv run python complete_fastmcp_server.py
如果看到 "Server is ready to accept connections." 说明安装成功。
✨ 主要特性
支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 等阿里云服务，可对云服务器、虚拟私有云、关系型数据库、对象存储等进行管理和操作。
📦 安装指南
安装 uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 pip
pip install uv
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
克隆项目
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp
一键安装
# 运行安装脚本（推荐）
./install.sh
# 或者手动安装
uv sync
cp .env.example .env
# 编辑 .env 文件，填入你的阿里云凭证
💻 使用示例
Amazon Q CLI 配置
在 ~/.aws/amazonq/mcp.json 中添加以下配置：
{
"mcpServers": {
"alibaba-cloud-ops-mcp-server": {
"timeout": 30000,
"command": "uv",
"args": [
"--directory",
"/绝对路径/to/alicloud-ops-mcp",
"run",
"python",
"complete_fastmcp_server.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
},
"disabled": false,
"autoApprove": []
}
}
}
⚠️ 重要提示
将 /绝对路径/to/alicloud-ops-mcp 替换为项目的实际绝对路径。
配置示例
假设项目位于 /home/user/alicloud-ops-mcp：
{
"mcpServers": {
"alibaba-cloud-ops-mcp-server": {
"timeout": 30000,
"command": "uv",
"args": [
"--directory",
"/home/user/alicloud-ops-mcp",
"run",
"python",
"complete_fastmcp_server.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
},
"disabled": false,
"autoApprove": []
}
}
}
📚 详细文档
支持的服务
| 属性 | 详情 |
|---|---|
| 支持服务 | ECS（云服务器管理、实例操作、镜像管理）、VPC（虚拟私有云、网络配置、安全组）、RDS（关系型数据库管理、备份恢复）、OSS（对象存储、文件上传下载）、CloudMonitor（云监控、告警管理、指标查询）、OOS（运维编排、自动化任务） |
开发说明
项目结构
alicloud-ops-mcp/
├── pyproject.toml # 项目配置和依赖
├── requirements.txt # 依赖列表（兼容性）
├── complete_fastmcp_server.py # 主服务器文件
├── alibaba_cloud_ops_mcp_server/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # 服务器核心逻辑
│ ├── config.py # 配置管理
│ └── tools/ # 各服务工具
│ ├── __init__.py
│ ├── api_tools.py # 通用 API 工具
│ ├── cms_tools.py # CloudMonitor 工具
│ ├── common_api_tools.py # 公共 API 工具
│ ├── oos_tools.py # OOS 工具
│ └── oss_tools.py # OSS 工具
├── .env.example # 环境变量模板
├── .env # 环境变量（需要创建）
├── install.sh # 安装脚本
├── verify_setup.py # 验证脚本
├── README.md # 中文文档
├── README_EN.md # 英文文档
└── LICENSE
使用 uv 进行开发
# 安装开发依赖
uv sync --dev
# 运行测试
uv run pytest
# 运行服务器
uv run python complete_fastmcp_server.py
# 添加新依赖
uv add package-name
# 添加开发依赖
uv add --dev package-name
# 更新依赖
uv sync --upgrade
# 查看依赖树
uv tree
Python 版本管理
项目在 pyproject.toml 中指定了 Python 版本要求：
requires-python = ">=3.10"
uv 会自动：
- 检测并安装合适的 Python 版本
- 创建隔离的虚拟环境
- 管理所有依赖关系
- 确保跨平台兼容性
故障排除
常见问题
1. Permission denied (os error 13)
原因：配置错误或权限问题 解决方案：
# 确保使用 uv 命令而不是直接的 python 路径
uv run python complete_fastmcp_server.py
# 检查项目路径是否正确
pwd
# 确保脚本有执行权限
chmod +x complete_fastmcp_server.py
2. Python 版本不兼容
错误信息：Could not find a version that satisfies the requirement fastmcp>=2.8.0
解决方案：
# uv 会自动处理 Python 版本，无需手动安装
uv sync
# 如果仍有问题，清理并重新安装
uv clean
uv sync
3. 依赖安装失败
解决方案：
# 清理缓存并重新安装
uv clean
uv sync
# 查看详细错误信息
uv sync --verbose
4. 环境变量未加载
解决方案：
# 确保 .env 文件存在且格式正确
ls -la .env
cat .env
# 检查环境变量格式
uv run python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('Access Key ID:', os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID', 'Not found'))
print('Region:', os.getenv('ALIBABA_CLOUD_REGION', 'Not found'))
"
5. MCP 服务器无法启动
解决方案：
# 检查 Amazon Q CLI 配置
cat ~/.aws/amazonq/mcp.json
# 验证路径是否正确
ls -la /绝对路径/to/alicloud-ops-mcp/complete_fastmcp_server.py
# 测试服务器直接启动
cd /绝对路径/to/alicloud-ops-mcp
uv run python complete_fastmcp_server.py
调试模式
启用详细日志：
# 设置环境变量启用调试
export FASTMCP_LOG_LEVEL=DEBUG
uv run python complete_fastmcp_server.py
# 或者在 .env 文件中设置
echo "FASTMCP_LOG_LEVEL=DEBUG" >> .env
验证配置
运行完整的环境检查：
# 运行验证脚本
uv run python verify_setup.py
# 检查特定组件
uv run python -c "
import sys
print(f'Python version: {sys.version}')
try:
import fastmcp
print(f'FastMCP version: {fastmcp.__version__}')
except ImportError as e:
print(f'FastMCP import error: {e}')
try:
from alibaba_cloud_ops_mcp_server import server
print('Server module loaded successfully')
except ImportError as e:
print(f'Server module error: {e}')
"
性能优化
启动优化
# 预编译 Python 字节码
uv run python -m compileall .
# 使用更快的启动选项
uv run python -O complete_fastmcp_server.py
内存优化
在 .env 文件中添加：
# 限制内存使用
PYTHONHASHSEED=0
PYTHONDONTWRITEBYTECODE=1
贡献指南
- Fork 项目
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 安装开发依赖 (
uv sync --dev) - 运行测试 (
uv run pytest) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
开发环境设置
# 克隆仓库
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp
# 安装开发依赖
uv sync --dev
# 设置 pre-commit hooks
uv run pre-commit install
# 运行测试
uv run pytest
# 代码格式化
uv run black .
uv run isort .
# 类型检查
uv run mypy .
🔧 技术细节
Python 版本管理
项目通过 pyproject.toml 指定 Python 版本要求为 3.10+，uv 会自动检测并安装合适的 Python 版本，创建隔离的虚拟环境，管理所有依赖关系，确保跨平台兼容性。
服务器核心逻辑
complete_fastmcp_server.py 是主服务器文件，alibaba_cloud_ops_mcp_server/server.py 包含服务器核心逻辑，负责处理各种阿里云服务的请求和响应。
配置管理
alibaba_cloud_ops_mcp_server/config.py 负责配置管理，通过 .env 文件加载环境变量，如阿里云访问凭证等。
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
支持
如果遇到问题，请：
- 查看 故障排除 部分
- 运行
uv run python verify_setup.py检查环境 - 查看 GitHub Issues
- 创建新的 Issue 报告问题
获取帮助
更新日志
v0.9.2 (2024-12-XX)
- ✨ 支持使用 uv 进行包管理
- 🚀 简化安装和配置流程
- 🐛 改进错误处理和调试信息
- 📚 更新文档和故障排除指南
- 🔧 添加环境验证脚本
- 📦 添加一键安装脚本
v0.9.1
- 🔧 修复依赖版本兼容性问题
- 📝 改进文档结构
- 🐛 修复环境变量加载问题
v0.9.0
- 🎉 初始版本发布
- ✅ 支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 服务
- 🔐 支持阿里云访问凭证配置
- 📖 完整的文档和示例
致谢
感谢所有贡献者和社区成员的支持！
⭐ 如果这个项目对你有帮助，请给个 Star！