Alicloud Ops MCP

🚀 阿里雲操作 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": []
    }
  }
}

📚 詳細文檔

支持的服務

開發說明

項目結構

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

貢獻指南

1. Fork 項目
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 安裝開發依賴 (uv sync --dev)
4. 運行測試 (uv run pytest)
5. 提交更改 (git commit -m 'Add some amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 創建 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 文件瞭解詳情。

支持

如果遇到問題，請：

1. 查看 故障排除 部分
2. 運行 uv run python verify_setup.py 檢查環境
3. 查看 GitHub Issues
4. 創建新的 Issue 報告問題

獲取幫助

• 📖 文檔
• 🐛 報告 Bug
• 💡 功能請求
• 💬 討論

更新日誌

v0.9.2 (2024-12-XX)

• ✨ 支持使用 uv 進行包管理
• 🚀 簡化安裝和配置流程
• 🐛 改進錯誤處理和調試信息
• 📚 更新文檔和故障排除指南
• 🔧 添加環境驗證腳本
• 📦 添加一鍵安裝腳本

v0.9.1

• 🔧 修復依賴版本兼容性問題
• 📝 改進文檔結構
• 🐛 修復環境變量加載問題

v0.9.0

• 🎉 初始版本發佈
• ✅ 支持 ECS、VPC、RDS、OSS、CloudMonitor、OOS 服務
• 🔐 支持阿里雲訪問憑證配置
• 📖 完整的文檔和示例

致謝

感謝所有貢獻者和社區成員的支持！

⭐ 如果這個項目對你有幫助，請給個 Star！