Alibaba Cloud Operations MCP Server

一个用于 Amazon Q CLI 的阿里云操作 MCP 服务器，支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 等服务。

系统要求

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." 说明安装成功。

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 .

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

支持

如果遇到问题，请：

查看故障排除部分
运行 uv run python verify_setup.py 检查环境
查看 GitHub Issues
创建新的 Issue 报告问题

获取帮助

📖 文档
🐛 报告 Bug
💡 功能请求
💬 讨论

更新日志

v0.9.2 (2024-12-XX)

✨ 支持使用 uv 进行包管理
🚀 简化安装和配置流程
🐛 改进错误处理和调试信息
📚 更新文档和故障排除指南
🔧 添加环境验证脚本
📦 添加一键安装脚本

v0.9.1

🔧 修复依赖版本兼容性问题
📝 改进文档结构
🐛 修复环境变量加载问题

v0.9.0

🎉 初始版本发布
✅ 支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 服务
🔐 支持阿里云访问凭证配置
📖 完整的文档和示例

致谢

感谢所有贡献者和社区成员的支持！

⭐ 如果这个项目对你有帮助，请给个 Star！

Alibaba Cloud Operations MCP Server

系统要求

快速开始

1. 安装 uv

2. 克隆项目

3. 一键安装

4. 配置环境变量

5. 验证安装

Amazon Q CLI 配置

配置示例

支持的服务

开发说明

项目结构

使用 uv 进行开发

Python 版本管理

故障排除

常见问题

1. Permission denied (os error 13)

2. Python 版本不兼容

3. 依赖安装失败

4. 环境变量未加载

5. MCP 服务器无法启动

调试模式

验证配置

性能优化

启动优化

内存优化

贡献指南

开发环境设置

许可证

支持

获取帮助

更新日志

v0.9.2 (2024-12-XX)

v0.9.1

v0.9.0

致谢

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API