Content
# Alibaba Cloud Operations MCP Server
An Alibaba Cloud Operations MCP Server for Amazon Q CLI, supporting services such as ECS, VPC, RDS, OSS, CloudMonitor, OOS, etc.
[English](README_EN.md) | 中文
## System Requirements
- Python 3.10+ (managed automatically by uv)
- [uv](https://docs.astral.sh/uv/) - Python package and project manager
- Alibaba Cloud access credentials
## Quick Start
### 1. Install uv
```bash
# 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
```bash
git clone https://github.com/your-username/alicloud-ops-mcp.git
cd alicloud-ops-mcp
```
### 3. One-Click Installation
```bash
# 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:
```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. Verify Installation
```bash
# Run the verification script
uv run python verify_setup.py
# Test server startup
uv run python complete_fastmcp_server.py
```
If you see "Server is ready to accept connections.", the installation was successful.
## Amazon Q CLI Configuration
Add the following configuration to `~/.aws/amazonq/mcp.json`:
```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
Assuming the project is located at `/home/user/alicloud-ops-mcp`:
```json
{
"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": []
}
}
}
```
## Supported Services
| Service | Functionality | Status |
|---------|---------------|--------|
| **ECS** | Cloud server management, instance operations, image management | ✅ |
| **VPC** | Virtual Private Cloud, network configuration, security groups | ✅ |
| **RDS** | Relational database management, backup and recovery | ✅ |
| **OSS** | Object storage, file upload and download | ✅ |
| **CloudMonitor** | Cloud monitoring, alarm management, metric queries | ✅ |
| **OOS** | Operations orchestration, automation tasks | ✅ |
## Development Instructions
### 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 # Core server logic
│ ├── config.py # Configuration management
│ └── tools/ # Tools for various services
│ ├── __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 (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
```bash
# 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 dependency tree
uv tree
```
### Python Version Management
The project specifies the Python version requirement in `pyproject.toml`:
```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:**
```bash
# 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. Incompatible Python version
**Error Message:** `Could not find a version that satisfies the requirement fastmcp>=2.8.0`
**Solution:**
```bash
# uv will automatically handle Python version, no manual installation needed
uv sync
# If issues persist, clean and reinstall
uv clean
uv sync
```
#### 3. Dependency installation failed
**Solution:**
```bash
# Clean cache and reinstall
uv clean
uv sync
# View detailed error messages
uv sync --verbose
```
#### 4. Environment variables not loaded
**Solution:**
```bash
# Ensure the .env file exists and is formatted correctly
ls -la .env
cat .env
# Check the format of environment variables
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:**
```bash
# Check Amazon Q CLI configuration
cat ~/.aws/amazonq/mcp.json
# Verify the path is correct
ls -la /absolute/path/to/alicloud-ops-mcp/complete_fastmcp_server.py
# Test server startup directly
cd /absolute/path/to/alicloud-ops-mcp
uv run python complete_fastmcp_server.py
```
### Debug Mode
Enable detailed logging:
```bash
# Set environment variable to enable debugging
export FASTMCP_LOG_LEVEL=DEBUG
uv run python complete_fastmcp_server.py
# Or set in the .env file
echo "FASTMCP_LOG_LEVEL=DEBUG" >> .env
```
### Validate Configuration
Run a complete environment check:
```bash
# 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
```bash
# 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:
```env
# 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
```bash
# 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](LICENSE) file for details.
## Support
If you encounter issues, please:
1. Check the [Troubleshooting](#troubleshooting) section
2. Run `uv run python verify_setup.py` to check the environment
3. Check [GitHub Issues](https://github.com/your-username/alicloud-ops-mcp/issues)
4. Create a new Issue to report a problem
### Get Help
- 📖 [Documentation](https://github.com/your-username/alicloud-ops-mcp/wiki)
- 🐛 [Report a Bug](https://github.com/your-username/alicloud-ops-mcp/issues/new?template=bug_report.md)
- 💡 [Feature Request](https://github.com/your-username/alicloud-ops-mcp/issues/new?template=feature_request.md)
- 💬 [Discussion](https://github.com/your-username/alicloud-ops-mcp/discussions)
## Changelog
### v0.9.2 (2024-12-XX)
- ✨ Support for package management using uv
- 🚀 Simplified installation and configuration process
- 🐛 Improved error handling and debugging information
- 📚 Updated documentation and troubleshooting guide
- 🔧 Added environment validation script
- 📦 Added one-click installation script
### v0.9.1
- 🔧 Fixed dependency version compatibility issues
- 📝 Improved documentation structure
- 🐛 Fixed environment variable loading issues
### v0.9.0
- 🎉 Initial version release
- ✅ Support for ECS, VPC, RDS, OSS, CloudMonitor, OOS services
- 🔐 Support for 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!**
