cPanel MCP Server

![MIT License](https://choosealicense.com/licenses/mit/) ![TypeScript](https://www.typescriptlang.org/) ![Node.js](https://nodejs.org/)

A comprehensive Model Context Protocol (MCP) server for managing cPanel web hosting accounts. This server provides tools to interact with cPanel's UAPI (Unified API) for common hosting management tasks, enabling seamless integration with AI assistants and automation workflows.

🚀 Features

File Management: Browse, list, and manage files through cPanel's File Manager
Database Operations: Create, delete, and list MySQL databases
Email Management: Manage email accounts with full CRUD operations
Domain Information: Retrieve domain and subdomain details
Cron Job Management: Schedule and manage automated tasks
System Monitoring: Monitor disk usage and account statistics
Backup Operations: Create and manage account backups
Secure Authentication: Support for both API tokens and password authentication

📋 Prerequisites

Node.js 18.0.0 or higher
A cPanel hosting account with API access
Either a cPanel password or API token for authentication

🛠️ Installation

Option 1: Clone and Build

git clone https://github.com/ringo380/cpanel-mcp.git
cd cpanel-mcp
npm install
npm run build

Option 2: Direct Installation

npm install -g cpanel-mcp

⚙️ Configuration

Environment Setup

Copy the example environment file:

cp .env.example .env

Configure your cPanel credentials in .env:

# Required: cPanel server details
CPANEL_HOSTNAME=your-cpanel-hostname.com
CPANEL_USERNAME=your-cpanel-username

# Authentication (choose one method)
CPANEL_API_TOKEN=your-api-token-here
# OR
CPANEL_PASSWORD=your-cpanel-password

# Optional: Connection settings
CPANEL_PORT=2083
CPANEL_SSL=true

Generating a cPanel API Token (Recommended)

Log into your cPanel account
Navigate to Security → Manage API Tokens
Click Create Token
Give it a descriptive name and set permissions
Copy the generated token to your .env file

🚀 Usage

Starting the Server

npm start

The server will start and listen for MCP connections via stdio.

Integration with Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "cpanel": {
      "command": "node",
      "args": ["/path/to/cpanel-mcp/dist/index.js"],
      "env": {
        "CPANEL_HOSTNAME": "your-hostname.com",
        "CPANEL_USERNAME": "your-username",
        "CPANEL_API_TOKEN": "your-token"
      }
    }
  }
}

🛠️ Available Tools

File Management

list_files - List files and directories in specified path

  {
    "name": "list_files",
    "arguments": {
      "path": "/public_html"
    }
  }

Database Management

list_databases - List all MySQL databases
create_database - Create a new MySQL database
delete_database - Delete an existing database

Email Management

list_email_accounts - List all email accounts (optionally filter by domain)
create_email_account - Create a new email account
delete_email_account - Delete an email account

Domain Operations

list_domains - List all domains and subdomains

Cron Job Management

list_cron_jobs - List all scheduled cron jobs
add_cron_job - Schedule a new cron job
delete_cron_job - Remove a cron job

System Information

get_disk_usage - Get detailed disk usage statistics

Backup Operations

create_backup - Create a full account backup
list_backups - List available backups

💡 Examples

Creating a Database and Email Account

// Create a new database
await callTool("create_database", {
  name: "myapp_db"
});

// Create an email account with 500MB quota
await callTool("create_email_account", {
  email: "support@mydomain.com",
  password: "secure_password_123",
  quota: 500
});

Managing Cron Jobs

// Add a daily backup cron job
await callTool("add_cron_job", {
  minute: "0",
  hour: "2",
  day: "*",
  month: "*",
  weekday: "*",
  command: "/usr/local/bin/backup_script.sh"
});

🔒 Security Considerations

Use API Tokens: Prefer API tokens over passwords for better security
Environment Variables: Never commit credentials to version control
Limited Scope: The server only exposes safe, account-level operations
HTTPS: Always use SSL/TLS connections to cPanel (enabled by default)

🧪 Development

Setup Development Environment

git clone https://github.com/ringo380/cpanel-mcp.git
cd cpanel-mcp
npm install
cp .env.example .env
# Edit .env with your test cPanel credentials

Development Commands

npm run dev        # Start in watch mode
npm run build      # Build TypeScript to JavaScript
npm run lint       # Run ESLint
npm run typecheck  # Run TypeScript type checking

Testing

npm test           # Run test suite
npm run test:watch # Run tests in watch mode

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Start for Contributors

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure tests pass: npm test
Commit with conventional commits: git commit -m "feat: add amazing feature"
Push to your fork and submit a pull request

📚 API Reference

cPanel UAPI Modules Used

Fileman: File management operations
Mysql: Database operations
Email: Email account management
DomainInfo: Domain information
Cron: Cron job management
StatsBar: Usage statistics
Backup: Backup operations

For detailed cPanel UAPI documentation, visit: cPanel UAPI Documentation

🐛 Troubleshooting

Common Issues

Connection Failed

Verify CPANEL_HOSTNAME is correct and accessible
Check that the specified port is open (default: 2083 for HTTPS)
Ensure SSL setting matches your cPanel configuration

Authentication Failed

Verify username and password/API token are correct
Check that API access is enabled for your account
Ensure API token has sufficient permissions

Tool Execution Errors

Check cPanel error logs for detailed error messages
Verify you have necessary permissions for the operation
Ensure target resources (databases, emails, etc.) exist

Debug Mode

Enable debug logging by setting: ``env DEBUG=cpanel-mcp:* ``

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol by Anthropic
cPanel UAPI documentation
The open source community for inspiration and tools

📞 Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📖 Documentation: Wiki

---

Star ⭐ this repository if you find it helpful!

cpanel-mcp