cpanel-mail-mcp: Connect Your cPanel Mailbox to Claude

Your Inbox Lives on cPanel, Your Assistant Does Not

A large share of small and mid-sized businesses still run their email on the same cPanel hosting account as their website. It is cheap, it is already paid for, and it works. The problem appears the moment a team starts doing real work inside Claude Code or the Claude desktop app: the assistant can read files, write code and draft documents, but the inbox where client requests, invoices and meeting invites actually arrive stays out of reach.

We built cpanel-mail-mcp to close that gap. It is a small, open-source MCP server that connects a single cPanel mailbox (IMAP for reading, SMTP for sending, CalDAV for the calendar) directly to Claude Code and the Claude desktop app. It runs over stdio on your own machine, so there is no OAuth shim, no reverse proxy and no always-on server to maintain.

Why cPanel needs a different approach

Most mail integrations assume a provider with OAuth or app-specific passwords. You click “allow”, the provider issues a scoped token, and the integration never sees your real password. cPanel mail offers neither. The only credential is the plain IMAP password, and that password is everything: it grants full rights to read the mailbox and to send mail as that person.

That single fact shaped the whole design. A central, shared server that holds every teammate’s mailbox would have to store every teammate’s plain password in one place. One breach would expose the entire team’s correspondence. So a central deployment was deliberately ruled out.

One mailbox per process

Instead, the server runs one mailbox per process. Each person runs their own instance, on their own machine, with their own credentials. The password never leaves that machine. If your team has five people, you have five small local processes rather than one large target.

Setup in One Command

The project ships a setup wizard, so nobody on the team has to edit configuration files by hand. With Node 20 or later installed, one command does the work:

npx -y https://github.com/Burak-Kumas/cpanel-mail-mcp/archive/refs/heads/main.tar.gz setup

The wizard walks through three steps:

• It asks for the cPanel mailbox username, password, server and IMAP/SMTP ports. Server and ports come pre-filled with the usual cPanel defaults.

• Before saving anything, it verifies the details with a real IMAP and SMTP login and detects whether a calendar is available on the account.

• It registers the server with both Claude Code and the Claude desktop app.

The server is copied to ~/.cpanel-mail-mcp/ because the npx cache is temporary, and settings are stored in ~/.cpanel-mail-mcp/.env with file mode 600, readable only by your user. The repository also includes a step-by-step guide in Turkish for teammates who prefer to follow along screen by screen.

What Claude Can Do With Your Mailbox

Once connected, Claude gets a set of tools grouped by purpose. You do not call them yourself; you ask in plain language and the assistant picks the right one.

Read, write and organize

• Read: list_folders, list_messages, search_messages, get_message, list_attachments and save_attachment.

• Write: send_message with attachments, reply_message that keeps thread headers and the quoted text (with replyAll support), forward_message with attachments, and create_draft.

• Organize: set_flags for seen, flagged and answered states, plus move_message, archive_message, mark_spam and trash_message.

Folders and calendar

• Folders: create_folder, rename_folder, delete_folder and empty_trash.

• Calendar: list_calendars, list_events, create_event, update_event and delete_event, available when a CalDAV address is configured (the wizard detects this for you).

Security Choices That Keep Mistakes Reversible

Giving an assistant write access to email deserves caution, so the defaults lean toward recoverability.

• The password stays local. Credentials live in a file only your user can read, on your machine, used by a process only you run.

• Permanent delete is off by default. delete_message is only exposed when ALLOW_DELETE=true is set explicitly.

• Trash is reversible. Regular deletion goes through trash_message, which moves mail to Trash where it can be restored.

• The inbox is protected. The INBOX folder cannot be deleted.

None of this replaces good judgement about what you ask an assistant to do, but it means that a misunderstood instruction usually costs a trip to the Trash folder rather than lost mail.

Everyday Workflows for Teams on cPanel Hosting

The value shows up in small, repeated tasks that used to require switching windows and copying text back and forth.

• Morning triage: ask Claude to list unread messages from the last day, summarize what needs a reply, and flag the ones that matter.

• Drafted, not sent: have the assistant prepare replies as drafts, then review and send them yourself from your usual mail client.

• Attachments into the project: find the brief or invoice a client sent and save the attachment straight into the folder you are working in.

• Inbox to calendar: turn a meeting request in an email into a calendar event without retyping the date, time and details.

• Tidy folders: move a client’s threads into a project folder, archive old newsletters and mark obvious spam in one request.

For agencies and businesses that host email next to their website, this fits naturally alongside the rest of the stack. The same hosting account that serves your site, and that our web design and development team often configures at launch, can now feed your daily assistant work too. It is also one more reason to keep hosting healthy over time, a theme we cover in our guide to website maintenance after launch.

The Technical Gotchas We Solved

cPanel’s mail stack behaves a little differently from the providers most libraries are tested against. A few of those differences would break a naive integration, so the server handles them directly.

Calendar discovery on cpdavd

cPanel’s cpdavd service returns the wrong href in its multistatus responses. Standard automatic CalDAV discovery fails on these servers with a “cannot find homeUrl” error, so the server performs discovery by hand.

Drafts, Sent and the desktop app

• Drafts folder name: on cPanel the drafts folder is INBOX.Drafts, not Drafts. The server finds it through the IMAP SPECIAL-USE flag instead of guessing the name.

• Sent copies: sending over SMTP does not put anything in the Sent folder. The server compiles the message once, sends it, and writes the same message to Sent with IMAP APPEND, so both copies share one Message-ID.

• The desktop app and Node: the Claude desktop app does not load your shell, so tools like nvm do not resolve there. Registration uses the absolute path to node rather than the bare command, which is why the server starts reliably in the desktop app as well as in Claude Code.

Message bodies are decoded with a proper mail parser too, because slicing headers out of the raw source produced unreadable output for multipart and base64-encoded messages.

Getting Started

If your team’s mail runs on cPanel and you already work in Claude, the fastest way to judge whether this helps is to install it for one mailbox and use it for a week. The source, the full tool list and the Turkish setup guide are all on GitHub.

Connecting assistants to business systems is part of a broader question about what models can see and do on your behalf, which we also explore from the other side in our piece on AI crawlers and llms.txt. If you would like help fitting tools like this into your site and hosting setup, our web development team can plan it with you.