cPanel MCP Server

A complete Model Context Protocol (MCP) server for managing cPanel hosting through AI assistants like Claude Code

🎯 Overview

This is a production-ready MCP server that enables natural language management of cPanel hosting accounts through AI assistants. Built from scratch with TypeScript, it provides 16 tools for comprehensive hosting management.

Why This Exists: The original cPanel MCP repository contained only documentation with no source code. This is a complete, working implementation that you can use today.

✨ Features

🗂️ File Management

• List Files - Browse directories and view contents

• Read Files - View file contents

• Write Files - Create or update files

• Delete Files - Remove files and directories

🗄️ Database Management

• List Databases - View all MySQL databases

• Create Database - Create new databases

• Delete Database - Remove databases

📧 Email Management

• List Email Accounts - View all email accounts

• Create Email - Add new email accounts with quotas

• Delete Email - Remove email accounts

🌐 Domain Management

• List Subdomains - View all subdomains

• Create Subdomain - Add new subdomains

• Delete Subdomain - Remove subdomains

💾 System & Security

• Disk Usage - Check storage statistics and quotas

• Full Backup - Initiate account backups

• Install SSL - Set up SSL certificates

🚀 Installation

Prerequisites

• Node.js 18 or higher

• cPanel account with API token access

• AI assistant that supports MCP (like Claude Code)

Setup Steps

1. Clone the Repository

   git clone https://github.com/aandersen2323/cpanel-mcp-server.git
   cd cpanel-mcp-server

2. Install Dependencies

   npm install

3. Build the Server

   npm run build

4. Configure Credentials

   cp .env.example .env
   # Edit .env with your cPanel credentials

5. Add to Your MCP Configuration

   For Claude Code (VS Code), add to .vscode/settings.json:

   {
     "mcp.servers": {
       "cpanel": {
         "command": "node",
         "args": ["/absolute/path/to/cpanel-mcp-server/build/index.js"],
         "env": {
           "CPANEL_USERNAME": "your_username@your_domain.com",
           "CPANEL_API_TOKEN": "your_api_token",
           "CPANEL_SERVER_URL": "https://your-domain.com:2083"
         }
       }
     }
   }

6. Restart Your AI Assistant The MCP server will auto-start and be ready to use!

📖 Usage Examples

Natural Language Commands

Once configured, you can use natural language to manage your hosting:

File Operations:

"List files in public_html directory"
"Read the contents of wp-config.php"
"Create a new file called test.html with Hello World"
"Delete the old-backup.tar.gz file"

Database Operations:

"Show me all databases"
"Create a new database called my_app_db"
"Delete the test_database database"

Email Management:

"List all email accounts"
"Create email account support@example.com with password SecurePass123"
"Delete email account old@example.com"

Subdomain Management:

"List all subdomains"
"Create subdomain 'blog' under example.com"
"Delete subdomain test.example.com"

System Information:

"Check disk usage"
"How much storage am I using?"
"Start a full account backup"

Direct Tool Calls

You can also call tools directly:

// List files
mcp__cpanel__list_files({ dir: "/public_html" })

// Read file
mcp__cpanel__read_file({ file: "/public_html/index.php" })

// Create database
mcp__cpanel__create_database({ name: "myapp" })

// Check disk usage
mcp__cpanel__disk_usage()

🛠️ Available Tools

🔐 Security

Generating a cPanel API Token

1. Log into your cPanel account

2. Go to Security → Manage API Tokens

3. Click Create to generate a new token

4. Copy the token and save it securely

5. Add it to your .env file

Best Practices

• ✅ Never commit .env file - Contains sensitive credentials

• ✅ Use API tokens, not passwords - More secure and can be revoked

• ✅ Rotate tokens regularly - Update every 90 days

• ✅ Use least privilege - Only grant necessary permissions

• ✅ Monitor access logs - Check cPanel logs regularly

Security Features

• Environment-based credential storage

• HTTPS/SSL encrypted API communication

• Basic authentication with API tokens

• No credentials in source code or logs

• Comprehensive .gitignore for sensitive files

🏗️ Architecture

cpanel-mcp-server/
├── src/
│   └── index.ts          # MCP server implementation
├── build/
│   ├── index.js          # Compiled JavaScript
│   └── *.map             # Source maps
├── .env.example          # Credential template
├── .gitignore           # Security rules
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
├── LICENSE              # MIT License
└── README.md            # This file

Technology Stack

• TypeScript - Type-safe development

• @modelcontextprotocol/sdk - MCP protocol implementation

• node-fetch - HTTP client for cPanel API

• cPanel UAPI - Modern cPanel API interface

📊 cPanel API Reference

Base URL Structure

https://your-domain.com:2083/execute/{Module}/{Function}

Authentication

Authorization: Basic base64(username:api_token)

API Modules Used

• Fileman - File operations

• Quota - Disk usage

• Mysql - Database management

• Email - Email accounts

• SubDomain - Subdomain management

• Backup - Backup operations

• SSL - Certificate management

🧪 Testing

Verify Installation

# Check Node.js version
node --version  # Should be 18+

# Build the server
npm run build

# Verify build output
ls build/index.js  # Should exist

Test with AI Assistant

After configuring in your AI assistant:

"Check my disk usage"
"List all subdomains"
"Show me all databases"

🐛 Troubleshooting

Server Won't Start

Problem: MCP server fails to start

Solutions:

• Verify Node.js is installed: node --version

• Check build output exists: ls build/index.js

• Rebuild: npm run build

• Check logs for error messages

Authentication Errors

Problem: "401 Unauthorized" or "403 Forbidden"

Solutions:

• Verify API token is correct in .env

• Check username format: user@domain.com

• Confirm cPanel URL includes port :2083

• Test credentials directly in cPanel

• Generate new API token if expired

File Paths Not Working

Problem: File operations fail

Solutions:

• Use absolute paths starting with /

• Check file permissions in cPanel

• Verify directory exists

• Test with cPanel File Manager first

🚀 Development

Build Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode (rebuild on changes)
npm run dev

# Start server directly
npm start

Project Structure

• src/index.ts - Main server implementation

• build/ - Compiled JavaScript output

• .env - Your credentials (not committed)

• .env.example - Template for credentials

🤝 Contributing

Contributions are welcome! Here's how you can help:

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

Development Setup

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

📝 Changelog

Version 1.0.0 (2025-10-09)

Initial Release

• ✅ Complete MCP server implementation

• ✅ 16 cPanel management tools

• ✅ TypeScript with full type safety

• ✅ File operations (list, read, write, delete)

• ✅ Database management (list, create, delete)

• ✅ Email management (list, create, delete)

• ✅ Subdomain management (list, create, delete)

• ✅ System monitoring (disk usage)

• ✅ Backup and SSL support

• ✅ Comprehensive documentation

• ✅ Security best practices

• ✅ Error handling

📞 Support

Resources

• cPanel API Documentation: https://api.docs.cpanel.net/

• MCP Protocol: https://modelcontextprotocol.io/

• Issues: https://github.com/aandersen2323/cpanel-mcp-server/issues

Common Issues

1. "Module not found" - Run npm install and npm run build

2. "Authentication failed" - Verify credentials in .env

3. "Cannot connect" - Check cPanel URL and port (usually 2083)

4. "Permission denied" - Verify API token has required permissions

📄 License

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

🙏 Acknowledgments

• Built for use with Claude Code

• Implements the Model Context Protocol

• Uses cPanel UAPI

⭐ Star This Repo

If this MCP server helps you manage your cPanel hosting more easily, please give it a star! ⭐

Built with ❤️ by Claude Code

Status: Production Ready ✅ Version: 1.0.0 Last Updated: October 9, 2025