Alicloud Ops MCP

🚀 Alibaba Cloud Operations MCP Server

An Alibaba Cloud Operations MCP Server for Amazon Q CLI, supporting services such as ECS, VPC, RDS, OSS, CloudMonitor, and OOS.

English | Chinese

🚀 Quick Start

📦 System Requirements

• Python 3.10+ (automatically managed by uv)
• uv - Python package and project manager
• Alibaba Cloud access credentials

1️⃣ Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or use pip
pip install uv

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2️⃣ Clone the Project

git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp

3️⃣ One-click Installation

# Run the installation script (recommended)
./install.sh

# Or install manually
uv sync
cp .env.example .env
# Edit the .env file and fill in your Alibaba Cloud credentials

4️⃣ Configure Environment Variables

Edit the .env file:

ALIBABA_CLOUD_ACCESS_KEY_ID="your_access_key_id"
ALIBABA_CLOUD_ACCESS_KEY_SECRET="your_access_key_secret"
ALIBABA_CLOUD_REGION="cn-beijing"

5️⃣ Verify the Installation

# Run the verification script
uv run python verify_setup.py

# Test the server startup
uv run python complete_fastmcp_server.py

If you see "Server is ready to accept connections.", the installation is successful.

⚙️ Amazon Q CLI Configuration

Add the following configuration to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "alibaba-cloud-ops-mcp-server": {
      "timeout": 30000,
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/alicloud-ops-mcp",
        "run",
        "python",
        "complete_fastmcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

⚠️ Important Note

Replace /absolute/path/to/alicloud-ops-mcp with the actual absolute path of the project.

📋 Configuration Example

Assume the project is located at /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": []
    }
  }
}

✨ Features

📚 Documentation

📁 Project Structure

alicloud-ops-mcp/
├── pyproject.toml              # Project configuration and dependencies
├── requirements.txt            # Dependency list (compatibility)
├── complete_fastmcp_server.py  # Main server file
├── alibaba_cloud_ops_mcp_server/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py              # Server core logic
│   ├── config.py              # Configuration management
│   └── tools/                 # Tools for each service
│       ├── __init__.py
│       ├── api_tools.py       # General API tools
│       ├── cms_tools.py       # CloudMonitor tools
│       ├── common_api_tools.py # Common API tools
│       ├── oos_tools.py       # OOS tools
│       └── oss_tools.py       # OSS tools
├── .env.example               # Environment variable template
├── .env                       # Environment variables (need to be created)
├── install.sh                 # Installation script
├── verify_setup.py            # Verification script
├── README.md                  # Chinese documentation
├── README_EN.md               # English documentation
└── LICENSE

💻 Development with uv

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run the server
uv run python complete_fastmcp_server.py

# Add new dependencies
uv add package-name

# Add development dependencies
uv add --dev package-name

# Update dependencies
uv sync --upgrade

# View the dependency tree
uv tree

🐍 Python Version Management

The project specifies the Python version requirements in pyproject.toml:

requires-python = ">=3.10"

uv will automatically:

• Detect and install the appropriate Python version
• Create an isolated virtual environment
• Manage all dependencies
• Ensure cross-platform compatibility

🔧 Troubleshooting

🛠️ Common Issues

1. Permission denied (os error 13)

Cause: Configuration error or permission issue Solution:

# Ensure to use the uv command instead of the direct python path
uv run python complete_fastmcp_server.py

# Check if the project path is correct
pwd

# Ensure the script has execution permissions
chmod +x complete_fastmcp_server.py

2. Python Version Incompatibility

Error message: Could not find a version that satisfies the requirement fastmcp>=2.8.0 Solution:

# uv will automatically handle the Python version, no manual installation is required
uv sync

# If the problem persists, clean and reinstall
uv clean
uv sync

3. Dependency Installation Failure

Solution:

# Clean the cache and reinstall
uv clean
uv sync

# View detailed error information
uv sync --verbose

4. Environment Variables Not Loaded

Solution:

# Ensure the .env file exists and has the correct format
ls -la .env
cat .env

# Check the environment variable format
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 Server Fails to Start

Solution:

# Check the Amazon Q CLI configuration
cat ~/.aws/amazonq/mcp.json

# Verify if the path is correct
ls -la /absolute/path/to/alicloud-ops-mcp/complete_fastmcp_server.py

# Test the direct startup of the server
cd /absolute/path/to/alicloud-ops-mcp
uv run python complete_fastmcp_server.py

🐞 Debug Mode

Enable detailed logging:

# Set the environment variable to enable debugging
export FASTMCP_LOG_LEVEL=DEBUG
uv run python complete_fastmcp_server.py

# Or set it in the .env file
echo "FASTMCP_LOG_LEVEL=DEBUG" >> .env

✅ Verify the Configuration

Run a complete environment check:

# Run the verification script
uv run python verify_setup.py

# Check specific components
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}')
"

⚡ Performance Optimization

⏱️ Startup Optimization

# Precompile Python bytecode
uv run python -m compileall .

# Use faster startup options
uv run python -O complete_fastmcp_server.py

💾 Memory Optimization

Add the following to the .env file:

# Limit memory usage
PYTHONHASHSEED=0
PYTHONDONTWRITEBYTECODE=1

🤝 Contribution Guidelines

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Install development dependencies (uv sync --dev)
4. Run tests (uv run pytest)
5. Commit changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Create a Pull Request

🛠️ Development Environment Setup

# Clone the repository
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp

# Install development dependencies
uv sync --dev

# Set up pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Code formatting
uv run black .
uv run isort .

# Type checking
uv run mypy .

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🛠️ Support

If you encounter any issues, please:

1. Check the Troubleshooting section
2. Run uv run python verify_setup.py to check the environment
3. Check GitHub Issues
4. Create a new Issue to report the problem

🆘 Get Help

• 📖 Documentation
• 🐛 Report a Bug
• 💡 Feature Request
• 💬 Discussions

📝 Changelog

v0.9.2 (2024-12-XX)

• ✨ Support package management with uv
• 🚀 Simplify the installation and configuration process
• 🐛 Improve error handling and debugging information
• 📚 Update documentation and troubleshooting guide
• 🔧 Add environment verification script
• 📦 Add one-click installation script

v0.9.1

• 🔧 Fix dependency version compatibility issues
• 📝 Improve documentation structure
• 🐛 Fix environment variable loading issues

v0.9.0

• 🎉 Initial version release
• ✅ Support ECS, VPC, RDS, OSS, CloudMonitor, OOS services
• 🔐 Support Alibaba Cloud access credential configuration
• 📖 Complete documentation and examples

🙏 Acknowledgments

Thanks to all contributors and community members for their support!

⭐ If this project is helpful to you, please give it a Star!