MCP EasyPanel Server

🚀 SPONSORED BY EASYPANEL - Support open source development through our link

💎 Multi-client MCP server for managing EasyPanel deployments from Claude, Cursor, Windsurf, Kiro, and Web IDEs

⭐ Star on GitHub ⬆️ | 🎯 Upgrade to Premium & Support Open Source

🤖 Universal AI IDE Support

MCP EasyPanel Server now supports all major AI development tools:

✅ Claude - Full MCP support with streaming
✅ Cursor - Optimized for developer workflows
✅ Windsurf - Enhanced error handling
✅ Kiro - REST API with synchronous execution
✅ Web IDEs - CORS-enabled REST API
✅ Generic MCP - Universal compatibility

📖 View Client Setup Guide | 🚀 Quick Start

💎 Free vs Premium - Why Premium is a Game-Changer

| Feature | Free Version | 🏆 Premium Version | |---------|-------------|-------------------| | Projects | ⚠️ Limited (3 projects) | ✅ Unlimited Projects | | Services | ⚠️ Limited (5 services) | ✅ Unlimited Services | | SSL Certificates | ⚠️ Manual setup | ✅ Free Auto SSL with Let's Encrypt | | Deployments | ⚠️ Queue delays | ✅ Priority Deployments | | Monitoring | ⚠️ Basic metrics | ✅ Advanced Monitoring & Alerts | | Support | ⚠️ Community only | ✅ Priority Support (24h response) | | Custom Domains | ⚠️ 1 domain only | ✅ Unlimited Custom Domains | | Database Backups | ⚠️ Manual only | ✅ Automated Daily Backups | | Security | ⚠️ Basic protection | ✅ Advanced Firewall & DDoS Protection |

🔥 Support Open Source Development - Upgrade Through Our Link

🚀 Upgrade to EasyPanel Premium & Support Open Source

When you upgrade through our link, you support continued development of this open-source MCP server while unlocking premium features!

🎯 Why Choose EasyPanel Premium?

📈 Scale Without Limits

Unlimited Projects - Deploy all your apps without constraints
Unlimited Services - Run as many microservices, databases, and apps as you need
Unlimited Domains - Host multiple projects with custom domains

🛡️ Enterprise Security

Free SSL Certificates - Automatic HTTPS for all your domains
Advanced Firewall - Protect against attacks and DDoS
Automated Backups - Daily backups with one-click restore

⚡ Performance & Support

Priority Build Queues - Deploy 10x faster with priority access
Advanced Monitoring - Real-time alerts and detailed analytics
24/7 Priority Support - Get help when you need it most

💡 Pro Tip: Most teams upgrade within 30 days once they see the productivity gains. Start with Premium and scale from day one!

🎁 Upgrade Now to Support Open Source Development

🚀 One-Line Installation

Option 1: Install from npm (Recommended)

npx easypanel-mcp-install

Option 2: Clone and Build

git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcp
npm install && npm run build

Option 3: Install as Global Package

npm install -g easypanel-mcp

⚠️ Note: This MCP server works with both Free and Premium EasyPanel. Upgrade to Premium to unlock advanced features!

🔧 Quick Setup for Your AI Client

For Claude Desktop

# The server auto-detects Claude when used with MCP
easypanel-mcp --transport stdio

For Cursor

# Optimized for Cursor with compact responses
easypanel-mcp --client cursor --transport stdio

For Windsurf

# Enhanced error handling for Windsurf
easypanel-mcp --client windsurf --transport sse --port 3001

For Kiro

# REST API for Kiro (synchronous mode)
easypanel-mcp --client kiro --transport rest --rest-port 3002

For Web IDEs

# CORS-enabled REST API for web integration
easypanel-mcp --transport rest --rest-port 3002

For All Clients (Development)

# Run all transports simultaneously
easypanel-mcp --transport all --http-port 3001 --rest-api-port 3002

🎯 Quick Start

🚀 Option 1: Claude Code with Environment Variables (Easiest)

# 1. Configure environment
echo "EASYPANEL_URL=http://your-server-ip:3000" > ~/.mcp-easypanel.env
echo "EASYPANEL_EMAIL=your-email@example.com" >> ~/.mcp-easypanel.env
echo "EASYPANEL_PASSWORD=your-password" >> ~/.mcp-easypanel.env

# 2. Add to Claude Code (reads from .env)
claude mcp add easypanel npx easypanel-mcp

# 3. Test connection
echo "List all projects to verify connection"

🔧 Option 2: Direct Configuration in Claude Code

# Add with explicit environment variables
claude mcp add easypanel npx easypanel-mcp \
  --env EASYPANEL_URL=http://your-server-ip:3000 \
  --env EASYPANEL_EMAIL=your-email@example.com \
  --env EASYPANEL_PASSWORD=your-password

🏠 Option 3: Local Project Setup

# 1. Clone and setup
git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcp
npm install && npm run build

# 2. Create .env file
cp .env.example .env
# Edit .env with your credentials:
# EASYPANEL_URL=http://your-server-ip:3000
# EASYPANEL_EMAIL=your-email@example.com
# EASYPANEL_PASSWORD=your-password

# 3. Add to Claude Code
claude mcp add easypanel node $(pwd)/dist/index.js

🌍 Option 4: Claude Desktop (Separate App)

Create/edit ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "easypanel": {
      "command": "npx",
      "args": ["easypanel-mcp"],
      "env": {
        "EASYPANEL_URL": "http://your-server-ip:3000",
        "EASYPANEL_EMAIL": "your-email@example.com",
        "EASYPANEL_PASSWORD": "your-password"
      }
    }
  }
}

💻 Option 5: VS Code with Claude Extension

{
  "mcp.servers": {
    "easypanel": {
      "command": "npx",
      "args": ["easypanel-mcp"]
    }
  }
}

Cursor IDE

{
  "mcp": {
    "servers": {
      "easypanel": {
        "command": "npx",
        "args": ["easypanel-mcp"]
      }
    }
  }
}

3. Verify Installation

# Test the connection
npx easypanel-mcp-test

# Or in Claude:
"List all projects to verify the connection works"

🌐 SSE Transport - Real-time Updates

The MCP EasyPanel Server now supports Server-Sent Events (SSE) transport for real-time progress monitoring and web-based dashboard integration!

🚀 Quick Start with SSE

# Start server with SSE transport (default port 3001)
easypanel-mcp --transport sse

# Custom port
easypanel-mcp --transport sse --port 8080

📊 Available Endpoints

POST /mcp - Main MCP endpoint for tool execution
GET /progress/{sessionId} - Real-time progress stream via SSE
GET /health - Server health check
GET /connections - Active connections monitor

🔄 Real-time Progress Support

Long-running operations now stream live progress:

Docker Cleanup: Image cleanup, container removal, volume pruning
System Operations: Full system prune, project-specific cleanup
Status Updates: Progress percentage, status messages, completion events

🌐 Web Dashboard

An example HTML client is included at examples/sse-client.html:

Start server: easypanel-mcp --transport sse
Open examples/sse-client.html in your browser
Execute Docker operations with live progress tracking

📖 Full Documentation

See docs/SSE_TRANSPORT.md for complete SSE transport documentation.

✨ Premium Features You'll Love

🏗️ Project Management

Create, list, inspect, and delete projects
Real-time project status tracking
Service orchestration within projects
Premium: Unlimited projects and services

🐳 Application Services

Deploy from Docker images, Git repositories, or Dockerfiles
Start, stop, restart, and redeploy services
Update environment variables and resource limits
Build logs access and monitoring
Premium: Priority deployments and advanced scaling

🗄️ Database Services

Create and manage Redis, MySQL, and PostgreSQL instances
Automatic connection string generation
Database credentials management
Premium: Automated daily backups and one-click restore

🌐 Domain & SSL Management

Add/remove custom domains
Premium: Automatic HTTPS with Let's Encrypt
Premium: Free SSL certificates for all domains
Custom SSL certificate upload
Certificate renewal management
Domain validation and DNS setup
Premium: Unlimited domains (vs 1 on free)

📊 Monitoring & Logs

Real-time service statistics (CPU, memory, network)
Container logs streaming and search
Performance metrics tracking
Log filtering and analysis
Premium: Advanced monitoring with alerts and notifications

🔐 Enterprise Security

JWT token-based authentication
Secure credential management
Session persistence
Error handling with retry logic
Premium: Advanced firewall and DDoS protection
Premium: Security audit logs and compliance
🔒 CVE-2025-55152 Secure - Built with pure Node.js/TypeScript, no React dependencies

🛡️ Security Notice

🔒 CVE-2025-55152 Safe Zone

This MCP EasyPanel Server is 100% immune to the Critical React Server Components vulnerability (CVE-2025-55152, CVSS 10.0).

Why We're Bulletproof:

✅ Zero React Dependencies - Pure Node.js/TypeScript architecture
✅ No Server Components - MCP Protocol, not React RSC
✅ Minimal Attack Surface - Only 3 core dependencies (@modelcontextprotocol/sdk, axios, zod)
✅ Server-Side Only - No frontend attack vectors

While Others Panic, You're Safe:

🚨 React apps worldwide are rushing to patch CVE-2025-55152
🛡️ Your MCP EasyPanel Server was never at risk
😌 Sleep well knowing your hosting management is secure

Peace of Mind Included: Focus on deploying great apps, not patching vulnerabilities.

📋 IDE-Specific Configuration

Claude Desktop Configuration

Linux: ~/.config/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "easypanel": {
      "command": "node",
      "args": ["/absolute/path/to/easypanel-mcp/dist/index.js"],
      "env": {
        "EASYPANEL_URL": "http://your-server-ip:3000",
        "EASYPANEL_EMAIL": "admin@example.com",
        "EASYPANEL_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code Project Configuration

Create .claude/mcp.json in your project:

{
  "mcpServers": {
    "easypanel": {
      "command": "npx",
      "args": ["easypanel-mcp@latest"],
      "env": {
        "EASYPANEL_URL": "http://your-server-ip:3000",
        "EASYPANEL_EMAIL": "admin@example.com",
        "EASYPANEL_PASSWORD": "your-password"
      }
    }
  }
}

VS Code with Claude Extension

Add to your .vscode/settings.json:

{
  "claude.mcp.servers": {
    "easypanel": {
      "command": "npx",
      "args": ["easypanel-mcp"]
    }
  },
  "claude.env": {
    "EASYPANEL_URL": "http://your-server-ip:3000",
    "EASYPANEL_EMAIL": "admin@example.com",
    "EASYPANEL_PASSWORD": "your-password"
  }
}

🛠️ Available Tools

📁 Project Management

| Tool | Description | Example | |------|-------------|---------| | list_projects | List all projects and their services | "Show me all my projects" | | create_project | Create a new project | "Create a project called 'webapp'" | | inspect_project | Get detailed project information | "Inspect the 'webapp' project" | | destroy_project | Delete a project | "Delete the project 'old-project'" |

🐳 Application Services

| Tool | Description | Example | |------|-------------|---------| | create_app_service | Create a new app service | "Create an app service 'api' in project 'webapp'" | | deploy_from_image | Deploy from Docker image | "Deploy nginx:latest to service 'web'" | | deploy_from_git | Deploy from Git repository | "Deploy from https://github.com/user/repo.git" | | deploy_from_dockerfile | Deploy using Dockerfile | "Deploy the current directory using Dockerfile" | | start_service | Start a stopped service | "Start service 'api' in project 'webapp'" | | stop_service | Stop a running service | "Stop service 'api'" | | restart_service | Restart a service | "Restart the 'api' service" | | redeploy_service | Trigger new deployment | "Redeploy the 'api' service" | | destroy_service | Delete a service | "Delete the service 'old-api'" | | update_env | Update environment variables | "Set DATABASE_URL=postgresql://..." | | update_resources | Update memory/CPU limits | "Set memory to 2048MB and CPU to 2 cores" | | get_service_logs | Get service logs | "Show me the last 100 lines of logs" | | get_service_stats | Get resource statistics | "Show CPU and memory usage for 'api'" |

🗄️ Database Services

| Tool | Description | Example | |------|-------------|---------| | create_redis | Create Redis instance | "Create a Redis database called 'cache'" | | inspect_redis | Get Redis connection info | "Show Redis connection details" | | create_mysql | Create MySQL database | "Create MySQL db 'mydb' with user 'app'" | | create_postgres | Create PostgreSQL database | "Create PostgreSQL db 'mydb'" | | destroy_db_service | Delete database service | "Delete Redis service 'cache'" | | update_redis_password | Update Redis password | "Update Redis 'cache' password" |

🌐 Domain & SSL Management (Premium Features)

| Tool | Description | Example | |------|-------------|---------| | add_domain | Add custom domain to service | "Add example.com to service 'web'" | | remove_domain | Remove domain from service | "Remove domain with ID '123'" | | list_domains | List all domains for service | "Show all domains for service 'web'" | | validate_domain | Validate domain and DNS | "Validate domain setup for example.com" | | enable_https | Enable HTTPS with Let's Encrypt | "Enable HTTPS for example.com" | | disable_https | Disable HTTPS for domain | "Disable HTTPS for example.com" | | renew_certificate | Renew SSL certificate | "Renew SSL certificate for domain" | | get_certificate | Get SSL certificate details | "Show SSL certificate info" | | upload_custom_certificate | Upload custom SSL cert | "Upload custom certificate" |

🔍 License Management

| Tool | Description | Example | |------|-------------|---------| | get_license_status | Check license status | "Show current EasyPanel license status" | | get_user_info | Get user information | "Display user account details" | | activate_license | Activate license | "Activate EasyPanel Premium license" |

📊 Advanced Monitoring

| Tool | Description | Example | |------|-------------|---------| | get_advanced_stats | System-wide statistics | "Show advanced system stats" | | get_system_stats | CPU, memory, disk stats | "Display system resource usage" | | get_docker_task_stats | Container statistics | "Show Docker container metrics" | | get_monitor_table_data | Dashboard data | "Get monitoring dashboard data" |

💡 Usage Examples

🚀 Deploy a Full-Stack Application

Create a project called "myapp"
Create a PostgreSQL database called "db" with user "app" and password "secret123"
Create an app service called "api"
Set environment variables:
- DATABASE_URL=postgresql://app:secret123@myapp_db:5432/myapp
- NODE_ENV=production
- PORT=3000
Deploy the API from https://github.com/user/api.git
Create another service called "frontend"
Deploy the frontend from the current directory using Dockerfile
Add domain myapp.com to the frontend service
Enable HTTPS for myapp.com

📊 Monitor and Scale

Show me the resource usage for all services in project "myapp"
Get the last 50 lines of logs from the "api" service
Update resources for service "api":
- Memory limit: 2048 MB
- CPU limit: 2.0 cores
Restart the "api" service to apply changes

🔐 SSL Certificate Management

Add domain api.example.com to service "api"
Validate the domain setup
Enable HTTPS for api.example.com with email admin@example.com
Check the certificate details
Upload a custom certificate for legacy.example.com

🗃️ Database Operations

Create a Redis cache instance called "session-store"
Create a MySQL database with:
- Database name: "production"
- User: "app"
- Password: "secure_password"
- Host: "mysql"
Show connection details for both databases

🔧 Advanced Configuration

Custom MCP Server Path

{
  "mcpServers": {
    "easypanel": {
      "command": "node",
      "args": ["/custom/path/to/dist/index.js"],
      "cwd": "/workspace"
    }
  }
}

Using Environment Variables in Production

# Production setup with systemd
sudo tee /etc/systemd/system/mcp-easypanel.service > /dev/null <<EOF
[Unit]
Description=MCP EasyPanel Server
After=network.target

[Service]
Type=simple
User=mcp
Environment=EASYPANEL_URL=https://panel.example.com
Environment=EASYPANEL_EMAIL=claude@example.com
Environment=EASYPANEL_PASSWORD=\${EASYPANEL_PASSWORD}
Environment=CACHE_TTL=600
ExecStart=/usr/bin/node /opt/easypanel-mcp/dist/index.js
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable mcp-easypanel
sudo systemctl start mcp-easypanel

Docker Deployment

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
RUN chmod +x ./dist/index.js

ENV NODE_ENV=production
EXPOSE 3000

CMD ["node", "dist/index.js"]

# docker-compose.yml
version: '3.8'
services:
  mcp-easypanel:
    build: .
    environment:
      - EASYPANEL_URL=${EASYPANEL_URL}
      - EASYPANEL_EMAIL=${EASYPANEL_EMAIL}
      - EASYPANEL_PASSWORD=${EASYPANEL_PASSWORD}
    restart: unless-stopped

🛠️ Development Setup

Prerequisites

Node.js >= 18.0.0
TypeScript >= 5.0.0
Git
An EasyPanel instance (free tier works perfectly!)

Local Development

# Clone the repository
git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcp

# Install dependencies
npm install

# Development mode with hot reload
npm run watch

# Run directly with tsx
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Run the built version
npm start

Project Structure

easypanel-mcp/
├── src/
│   ├── api/           # EasyPanel API client
│   ├── tools/         # MCP tool implementations
│   ├── types/         # TypeScript type definitions
│   └── index.ts       # Main server entry point
├── tests/             # Test files
├── docs/              # Documentation
├── examples/          # Usage examples
├── dist/              # Compiled JavaScript
└── package.json

Adding New Tools

Create a new tool file in src/tools/
Export a tools object and handler function
Import and register in src/index.ts

Example:

// src/tools/mytool.ts
export const myTool = {
  name: 'my_tool',
  description: 'My custom tool',
  inputSchema: {
    type: 'object',
    properties: { /* ... */ },
    required: [/* ... */]
  }
};

export async function handleMyTool(name: string, args: unknown) {
  // Implementation
  return { content: [{ type: 'text', text: 'Result' }] };
}

🔍 Troubleshooting

Connection Issues

Error: Connection refused

# Check if EasyPanel is accessible
curl http://your-server-ip:3000/api/trpc/auth.getSession

# Verify firewall settings
sudo ufw status
sudo ufw allow 3000/tcp

Error: Authentication failed

Verify your EasyPanel credentials
Check if the user has admin permissions
Try logging in via the EasyPanel web UI first
Ensure you're using the correct URL (include http:// or https://)

Service Not Found

# Service names in EasyPanel are lowercase with hyphens
# Correct: "my-app", "api-service"
# Incorrect: "MyApp", "API_SERVICE"

Common Errors

| Error | Solution | |-------|----------| | ECONNREFUSED | Check EasyPanel URL and firewall | | 401 Unauthorized | Verify email/password are correct | | 403 Forbidden | User needs admin permissions | | Service not found | Check service name format (lowercase-hyphens) | | Domain already exists | Domain must be unique across all services |

Debug Mode

Enable debug logging:

export DEBUG=easypanel:*
node dist/index.js

Or in your .env:

DEBUG=easypanel:*

Performance Issues

Enable caching (default: on)
```
CACHE_ENABLED=true
CACHE_TTL=300
```

Monitor cache statistics

const stats = client.getCacheStats();
console.log(`Hit rate: ${stats.hitRate}%`);

Adjust timeouts for slow connections

const client = new EasyPanelClient({
  timeout: 30000, // 30 seconds
  retryAttempts: 3
});

🔒 Security Best Practices

Never hardcode credentials in code - Always use environment variables
Use a dedicated API user with minimal required permissions
Rotate credentials regularly
Use HTTPS in production - EASYPANEL_URL=https://...
Consider using JWT tokens instead of passwords for long-running sessions
Audit access logs in EasyPanel regularly

📚 Additional Resources

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🌟 Don't Forget to Star Us!

⭐ If this MCP server helps you deploy faster, please give us a star on GitHub! ⭐

Star on GitHub

Every star helps us reach more developers and continue maintaining this project.

💎 Ready to Upgrade to Premium?

You've seen how powerful this MCP server is. Imagine what you can do with:

✅ Unlimited Projects & Services ✅ Free SSL Certificates for All Domains ✅ Priority Deployments (10x Faster) ✅ Advanced Monitoring & Alerts ✅ Automated Daily Backups ✅ 24/7 Priority Support ✅ Advanced Security Features

🔥 Support This Project - Upgrade Through Our Link

🎁 Premium Features + Support Open Source When you upgrade through our link:

🚀 Upgrade to Premium & Support Our Development

💡 Why wait? Most teams see 10x productivity increase after switching to Premium. Upgrade now to support continued development and scale unlimited!

🆘 Support

📖 Documentation
🐛 Issue Tracker
💬 Discussions
🚀 EasyPanel Support (for hosting questions)
💎 Premium Support for Premium Users

🎉 Acknowledgments

EasyPanel for providing the amazing hosting platform and sponsoring this project
Anthropic for creating Claude and the Model Context Protocol
All contributors who help make this project better
You, for supporting open-source development!

⭐ Star on GitHub | 🎯 Upgrade to Premium | ❤️ Support Open Source ⭐

Made with ❤️ by the MCP EasyPanel Server team
Proudly sponsored by EasyPanel