Content
# CapRover MCP Server
A production-grade Model Context Protocol (MCP) server for complete CapRover management through Claude Desktop and other MCP clients.
## Features
### Core Operations (All Implemented)
1. **App Creation & Deployment**
- Create new apps with persistent storage options
- Deploy from Docker images with full configuration
- Update existing apps (image, env vars, scaling)
2. **App Management**
- List all apps and projects
- Get detailed app information
- Stop running apps
- Scale applications
- Delete apps with optional volume removal
3. **Configuration**
- Set/update environment variables
- Add custom domains
- Enable SSL certificates
- Configure persistent directories
- Set up Git repository webhooks
4. **One-Click Apps**
- Deploy from CapRover's one-click registry
- Automated deployment with variables
- Support for WordPress, MySQL, PostgreSQL, Redis, etc.
5. **Monitoring** (Limited)
- App status and configuration
- Note: Direct log access requires SSH or web interface
## Quick Start
### Option 1: Docker (Required for Claude Desktop)
```bash
# Clone the repository
git clone https://github.com/yourusername/caprover-mcp.git
cd caprover-mcp
# Create .env from example
cp .env.example .env
# Generate base64 encoded password
python generate-token.py
# Copy the output to CAPROVER_PASSWORD_B64 in your Claude Desktop config
# Build the Docker image
docker build -t caprover-mcp:latest .
```
**Important**: MCP stdio servers must be run with `docker run -i` flag. The docker-compose.yml is only for building the image.
### Option 2: Direct Python
```bash
# Install dependencies
pip install -r requirements.txt
# Set environment variables
export CAPROVER_URL=https://captain.yourdomain.com
export CAPROVER_PASSWORD_B64=<base64-encoded-password>
# Run the server
python -m src.server
```
## Configuration
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"caprover": {
"command": "docker",
"args": [
"run",
"--rm",
"-p", "8080:8080",
"--name", "caprover-mcp",
"caprover-mcp:latest"
],
"env": {
"CAPROVER_URL": "https://captain.yourdomain.com",
"CAPROVER_PASSWORD_B64": "base64_encoded_password_here",
"MCP_TRANSPORT": "http",
"MCP_API_KEY": "optional-api-key"
}
}
}
}
```
### Password Security
Generate a base64 encoded password:
```bash
# Linux/Mac
echo -n "your-password" | base64
# Windows PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("your-password"))
# Using the MCP tool
# In Claude: "Use caprover_generate_password_token with my password"
```
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `CAPROVER_URL` | CapRover API URL | Yes | - |
| `CAPROVER_PASSWORD_B64` | Base64 encoded password | Yes* | - |
| `MCP_TRANSPORT` | Transport type | No | stdio |
*One password option required (B64 recommended)
## Usage Examples
**Note**: All tools are prefixed with `caprover_` for clarity. For example: `caprover_create_app`, `caprover_deploy_app_from_image`, etc.
### Create and Deploy Apps
```
"Create a new app called 'my-website' with persistent storage"
"Deploy nginx:latest to 'my-website' with 2 instances"
"Update 'my-app' with new image node:18-alpine"
```
### Manage Apps
```
"List all my CapRover apps"
"Stop the 'api-server' app"
"Scale 'web-app' to 3 instances"
"Delete 'old-app' and its volumes"
```
### Configure Apps
```
"Update 'my-app' with environment variables: DATABASE_URL=..., API_KEY=..."
"Add domain app.example.com to 'my-app'"
"Enable SSL for app.example.com on 'my-app'"
```
### One-Click Deployment
```
"Deploy wordpress one-click app as 'my-blog'"
"Deploy postgres one-click app as 'main-db' with password variables"
"Install redis one-click app"
```
### App Information
```
"Get details about 'web-app'"
"List all projects"
```
## Deployment
### Deploy to CapRover
1. Create a new app in CapRover named `caprover-mcp`
2. Deploy using Git:
```bash
git remote add caprover https://captain.yourdomain.com/git/caprover-mcp
git push caprover main
```
3. Set environment variables in CapRover:
- `CAPROVER_URL`
- `CAPROVER_PASSWORD_B64`
- `MCP_API_KEY` (if using authentication)
### Deploy to Other Platforms
The Docker image can be deployed to any platform supporting containers:
- AWS ECS/Fargate
- Google Cloud Run
- Azure Container Instances
- Kubernetes
- Any VPS with Docker
## Development
### Project Structure
```
caprover-mcp/
├── src/
│ └── server.py # Main MCP server implementation
├── Dockerfile # Multi-stage production build
├── docker-compose.yml # Local development setup
├── captain-definition # CapRover deployment config
├── requirements.txt # Python dependencies
├── .env.example # Environment template
└── README.md # This file
```
### Testing the Setup
```bash
# Test imports and connection
python test-connection.py
# Test with environment variables
export CAPROVER_URL=https://captain.yourdomain.com
export CAPROVER_PASSWORD_B64=<your-base64-password>
python test-connection.py
```
### Running Tests
```bash
# Install dev dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/
# Run with coverage
pytest --cov=src tests/
```
### Building Docker Image
```bash
# Build for local testing
docker build -t caprover-mcp:latest .
# Build for production
docker build --target runtime -t caprover-mcp:prod .
```
## Security Considerations
1. **Password Storage**: Always use base64 encoding or encryption for passwords
2. **API Authentication**: Enable `MCP_API_KEY` for remote deployments
3. **Network Security**: Use HTTPS for all CapRover communications
4. **Container Security**: Runs as non-root user (uid 1000)
5. **Resource Limits**: Configured in docker-compose.yml
## Troubleshooting
### Connection Issues
```bash
# Test CapRover connection
curl -X POST https://captain.yourdomain.com/api/v2/login \
-H "Content-Type: application/json" \
-d '{"password":"your-password"}'
# Check MCP server health
curl http://localhost:8080/health
```
### Common Errors
1. **"CAPROVER_URL environment variable is required"**
- Set the `CAPROVER_URL` in your environment or .env file
2. **"No valid CapRover password found"**
- Ensure `CAPROVER_PASSWORD_B64` is set correctly
3. **"Failed to connect to CapRover"**
- Check your CapRover URL and network connectivity
- Verify your password is correct
### Debug Mode
Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - See LICENSE file for details
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Uses [caprover-api](https://pypi.org/project/caprover-api/) Python client
- Inspired by the MCP ecosystem and community
