Multi-client MCP Server for EasyPanel - supports Claude, Cursor, Windsurf, Kiro, and Web IDEs
npm install easypanel-mcp




> 🚀 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
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
---
| 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 |
🚀 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!
---
> 💡 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
---
bash
npx easypanel-mcp-install
`$3
`bash
git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcp
npm install && npm run build
`$3
`bash
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
$3
`bash
The server auto-detects Claude when used with MCP
easypanel-mcp --transport stdio
`$3
`bash
Optimized for Cursor with compact responses
easypanel-mcp --client cursor --transport stdio
`$3
`bash
Enhanced error handling for Windsurf
easypanel-mcp --client windsurf --transport sse --port 3001
`$3
`bash
REST API for Kiro (synchronous mode)
easypanel-mcp --client kiro --transport rest --rest-port 3002
`$3
`bash
CORS-enabled REST API for web integration
easypanel-mcp --transport rest --rest-port 3002
`$3
`bash
Run all transports simultaneously
easypanel-mcp --transport all --http-port 3001 --rest-api-port 3002
`---
🎯 Quick Start
$3
`bash
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.env2. Add to Claude Code (reads from .env)
claude mcp add easypanel npx easypanel-mcp3. Test connection
echo "List all projects to verify connection"
`$3
`bash
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
`$3
`bash
1. Clone and setup
git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcp
npm install && npm run build2. 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
`$3
Create/edit
~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):`json
{
"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"
}
}
}
}
`$3
`json
{
"mcp.servers": {
"easypanel": {
"command": "npx",
"args": ["easypanel-mcp"]
}
}
}
`#### Cursor IDE
`json
{
"mcp": {
"servers": {
"easypanel": {
"command": "npx",
"args": ["easypanel-mcp"]
}
}
}
}
`$3
`bash
Test the connection
npx easypanel-mcp-testOr 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!
$3
`bash
Start server with SSE transport (default port 3001)
easypanel-mcp --transport sseCustom port
easypanel-mcp --transport sse --port 8080
`$3
-
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$3
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
$3
An example HTML client is included at
examples/sse-client.html:
1. Start server: easypanel-mcp --transport sse
2. Open examples/sse-client.html in your browser
3. Execute Docker operations with live progress tracking$3
See docs/SSE_TRANSPORT.md for complete SSE transport documentation.---
✨ Premium Features You'll Love
$3
- Create, list, inspect, and delete projects
- Real-time project status tracking
- Service orchestration within projects
- Premium: Unlimited projects and services$3
- 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$3
- Create and manage Redis, MySQL, and PostgreSQL instances
- Automatic connection string generation
- Database credentials management
- Premium: Automated daily backups and one-click restore$3
- 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)$3
- 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$3
- 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
$3
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
$3
Linux:
~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json`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"
}
}
}
}
`$3
Create
.claude/mcp.json in your project:`json
{
"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"
}
}
}
}
`$3
Add to your
.vscode/settings.json:`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
$3
| 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'" |$3
| 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'" |$3
| 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" |$3
| 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" |$3
| 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" |$3
| 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
$3
`text
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
`$3
`text
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
`$3
`text
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
`$3
`text
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
$3
`json
{
"mcpServers": {
"easypanel": {
"command": "node",
"args": ["/custom/path/to/dist/index.js"],
"cwd": "/workspace"
}
}
}
`$3
`bash
Production setup with systemd
sudo tee /etc/systemd/system/mcp-easypanel.service > /dev/null < [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
`$3
`dockerfile
FROM node:18-alpineWORKDIR /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"]
``yaml
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
$3
- Node.js >= 18.0.0
- TypeScript >= 5.0.0
- Git
- An EasyPanel instance (free tier works perfectly!)
$3
`bash
Clone the repository
git clone https://github.com/sitp2k/easypanel-mcp.git
cd easypanel-mcpInstall dependencies
npm installDevelopment mode with hot reload
npm run watchRun directly with tsx
npm run devRun tests
npm testBuild for production
npm run buildRun the built version
npm start
`$3
`
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
`$3
1. Create a new tool file in
src/tools/
2. Export a tools object and handler function
3. Import and register in src/index.tsExample:
`typescript
// 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
$3
Error:
Connection refused`bash
Check if EasyPanel is accessible
curl http://your-server-ip:3000/api/trpc/auth.getSessionVerify firewall settings
sudo ufw status
sudo ufw allow 3000/tcp
`Error:
Authentication failed1. Verify your EasyPanel credentials
2. Check if the user has admin permissions
3. Try logging in via the EasyPanel web UI first
4. Ensure you're using the correct URL (include http:// or https://)
$3
`bash
Service names in EasyPanel are lowercase with hyphens
Correct: "my-app", "api-service"
Incorrect: "MyApp", "API_SERVICE"
`$3
| 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 |$3
Enable debug logging:
`bash
export DEBUG=easypanel:*
node dist/index.js
`Or in your
.env:`
DEBUG=easypanel:*
`$3
1. Enable caching (default: on)
`
CACHE_ENABLED=true
CACHE_TTL=300
`2. Monitor cache statistics
`javascript
const stats = client.getCacheStats();
console.log(Hit rate: ${stats.hitRate}%);
`3. Adjust timeouts for slow connections
`javascript
const client = new EasyPanelClient({
timeout: 30000, // 30 seconds
retryAttempts: 3
});
`---
🔒 Security Best Practices
1. Never hardcode credentials in code - Always use environment variables
2. Use a dedicated API user with minimal required permissions
3. Rotate credentials regularly
4. Use HTTPS in production -
EASYPANEL_URL=https://...
5. Consider using JWT tokens instead of passwords for long-running sessions
6. Audit access logs in EasyPanel regularly---
📚 Additional Resources
- EasyPanel Documentation
- EasyPanel Pricing & Plans
- Model Context Protocol
- Claude Documentation
- MCP Server Development Guide
---
🤝 Contributing
Contributions are welcome! Please read our Contributing Guide for details.
$3
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)---
⭐ If this MCP server helps you deploy faster, please give us a star on GitHub! ⭐
Every star helps us reach more developers and continue maintaining this project.
---
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
🎁 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!
---
- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions
- 🚀 EasyPanel Support (for hosting questions)
- 💎 Premium Support for Premium Users
---
- 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