# cPanel MCP Server

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

---

## 🎯 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**
   ```bash
   git clone https://github.com/aandersen2323/cpanel-mcp-server.git
   cd cpanel-mcp-server
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Build the Server**
   ```bash
   npm run build
   ```

4. **Configure Credentials**
   ```bash
   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`:
   ```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:

```javascript
// 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

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

```bash
# 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

```bash
# 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

```bash
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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built for use with [Claude Code](https://claude.com/claude-code)
- Implements the [Model Context Protocol](https://modelcontextprotocol.io/)
- Uses [cPanel UAPI](https://api.docs.cpanel.net/)

---

## ⭐ 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