cpanel-mcp-server by aandersen2323 - MCP Server

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

Clone the Repository

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

Install Dependencies
```
npm install
```
Build the Server
```
npm run build
```

Configure Credentials

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

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"
      }
    }
  }
}

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

Tool	Description	Parameters
`cpanel_list_files`	List directory contents	`dir`: path (optional)
`cpanel_read_file`	Read file contents	`file`: full path
`cpanel_write_file`	Write/create file	`file`: path, `content`: text
`cpanel_delete_file`	Delete file/directory	`file`: path
`cpanel_disk_usage`	Get disk usage stats	None
`cpanel_list_databases`	List all databases	None
`cpanel_create_database`	Create database	`name`: database name
`cpanel_delete_database`	Delete database	`name`: database name
`cpanel_list_email_accounts`	List email accounts	`domain`: optional
`cpanel_create_email`	Create email account	`email`, `password`, `quota`
`cpanel_delete_email`	Delete email account	`email`: address
`cpanel_list_subdomains`	List subdomains	None
`cpanel_create_subdomain`	Create subdomain	`subdomain`, `domain`
`cpanel_delete_subdomain`	Delete subdomain	`subdomain`: full name
`cpanel_backup`	Full account backup	None
`cpanel_install_ssl`	Install SSL cert	`domain`: domain name

🔐 Security

Generating a cPanel API Token

Log into your cPanel account
Go to Security → Manage API Tokens
Click Create to generate a new token
Copy the token and save it securely
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:

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

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

"Module not found" - Run npm install and npm run build
"Authentication failed" - Verify credentials in .env
"Cannot connect" - Check cPanel URL and port (usually 2083)
"Permission denied" - Verify API token has required permissions

📄 License

This project is licensed under the MIT License - see the 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