sitp2k/easypanel-mcp

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

|

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

🔥 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:

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

📖 Full Documentation

See 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

🐳 Application Services

🗄️ Database Services

🌐 Domain & SSL Management (Premium Features)

🔍 License Management

📊 Advanced Monitoring

💡 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

1. Create a new tool file in src/tools/
2. Export a tools object and handler function
3. 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

1. 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://)

Service Not Found

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

Common Errors

Debug Mode

Enable debug logging:

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

Or in your .env:

DEBUG=easypanel:*

Performance Issues

1. Enable caching (default: on)

   CACHE_ENABLED=true
   CACHE_TTL=300
   

2. Monitor cache statistics

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

3. Adjust timeouts for slow connections

   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 for details.

Development Workflow

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)
5. 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