cpanel-mail-mcp 0.2.0__tar.gz

cpanel_mail_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Sauceda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cpanel_mail_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: cpanel-mail-mcp
+Version: 0.2.0
+Summary: MCP server for IMAP/SMTP email — multi-account, attachments, ICS calendar invites, drafts, Save-to-Sent.
+Author-email: Rodrigo Sauceda <rodrigo.sauceda@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rsauceda/cpanel-mail-mcp
+Project-URL: Repository, https://github.com/rsauceda/cpanel-mail-mcp
+Project-URL: Issues, https://github.com/rsauceda/cpanel-mail-mcp/issues
+Keywords: mcp,email,imap,smtp,cpanel,calendar,ics,attachments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# cpanel-mail-mcp
+
+MCP server for IMAP/SMTP email accounts — works with cPanel, Gmail
+(app passwords), Outlook, Fastmail, iCloud, or any provider that speaks
+plain IMAP + SMTP.
+
+## Features
+
+* **Multi-account** — manage multiple email accounts from different providers
+* **Read, search, list** — full IMAP support with folder browsing
+* **Send emails** — plain text, HTML, or both (multipart/alternative)
+* **Attachments** — send via file path or base64-encoded inline data
+* **Download attachments** — extract attachments from received emails as base64
+* **Calendar invites** — send proper ICS invitations with Accept/Decline buttons
+* **Save to Sent** — automatically saves sent emails to the Sent folder via IMAP
+* **Optional send gate** — configurable confirmation code to prevent accidental sends
+* **International folders** — handles UTF-7 encoded folder names (German, etc.)
+* **Compact MCP surface** — one `email` tool with lazy action discovery to reduce
+  client context use
+
+## Install
+
+### With `uvx` (recommended, no venv setup)
+
+```bash
+claude mcp add cpanel-mail \
+  -e CPANEL_USER=you@example.com \
+  -e CPANEL_PASS='your_password' \
+  -e CPANEL_SMTP_HOST=mail.example.com \
+  -e CPANEL_IMAP_HOST=mail.example.com \
+  -- uvx cpanel-mail-mcp
+```
+
+### With `pipx`
+
+```bash
+pipx install cpanel-mail-mcp
+claude mcp add cpanel-mail \
+  -e CPANEL_USER=you@example.com -e CPANEL_PASS='...' \
+  -e CPANEL_SMTP_HOST=mail.example.com -e CPANEL_IMAP_HOST=mail.example.com \
+  -- cpanel-mail-mcp
+```
+
+### Development install (from a git checkout)
+
+```bash
+git clone https://github.com/rsauceda/cpanel-mail-mcp
+cd cpanel-mail-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+cp .env.example .env         # edit
+cpanel-mail-mcp              # runs the stdio server
+# or: python -m cpanel_mail_mcp
+```
+
+## Configuration
+
+Three ways, in priority order:
+
+### 1. `EMAIL_ACCOUNTS_JSON` (best for multi-account)
+
+```bash
+export EMAIL_ACCOUNTS_JSON='[
+  {"name":"work","user":"me@work.com","password":"...",
+   "smtp_host":"mail.work.com","imap_host":"mail.work.com",
+   "sent_folder":"INBOX.Sent"},
+  {"name":"gmail","user":"me@gmail.com","password":"app_pass",
+   "smtp_host":"smtp.gmail.com","smtp_port":587,
+   "imap_host":"imap.gmail.com","sent_folder":"[Gmail]/Sent Mail"}
+]'
+```
+
+### 2. `EMAIL_ACCOUNTS_FILE`
+
+Point to a JSON file with the same shape.
+
+### 3. Legacy single-account (`CPANEL_*`)
+
+Backwards compatible with 0.1.x installs. See [`.env.example`](.env.example).
+
+### Account fields
+
+| field           | required | default   |
+|-----------------|----------|-----------|
+| `name`          | no       | `user`    |
+| `user`          | **yes**  | —         |
+| `password`      | **yes**  | —         |
+| `smtp_host`     | **yes**  | —         |
+| `smtp_port`     | no       | `465`     |
+| `imap_host`     | **yes**  | —         |
+| `imap_port`     | no       | `993`     |
+| `sent_folder`   | no       | `Sent`    |
+| `drafts_folder` | no       | `Drafts`  |
+| `save_to_sent`  | no       | `true`    |
+| `from_name`     | no       | —         |
+
+### Loading a dev `.env`
+
+The server auto-loads `.env` from the current working directory. Point it
+elsewhere with:
+
+```bash
+export EMAIL_ENV_FILE=/absolute/path/to/.env
+```
+
+## Usage — the `email` tool
+
+The server exposes **one** MCP tool named `email`. Call it with an `action`
+string and a `params` dict. Discover actions with `action='help'` — the
+default when `action` is omitted:
+
+```json
+{ "action": "help" }
+```
+
+### Actions at a glance
+
+| action                | purpose                                          |
+|-----------------------|--------------------------------------------------|
+| `help`                | list all actions and their signatures            |
+| `list_accounts`       | see configured accounts (no secrets returned)    |
+| `list_folders`        | list IMAP folders (UTF-7 decoded)                |
+| `list_recent`         | last N messages of a folder                      |
+| `search`              | IMAP search by FROM/TO/SUBJECT/BODY/TEXT         |
+| `read`                | read a message by UID (optionally with attachments) |
+| `download_attachments`| fetch attachments as base64                       |
+| `send`                | send an email (text/HTML/attachments)             |
+| `save_draft`          | append a draft to the account's Drafts folder     |
+| `send_invite`         | send an ICS calendar invite                       |
+
+### Send an email with an attachment
+
+```json
+{
+  "action": "send",
+  "params": {
+    "to": "someone@example.com",
+    "subject": "Report",
+    "text": "See attached.",
+    "html": "<p>See <b>attached</b>.</p>",
+    "attachments": [
+      {"path": "/tmp/report.pdf"},
+      {"name": "note.txt", "content": "hi from inline"}
+    ]
+  }
+}
+```
+
+Attachment shapes accepted:
+- `{"path": "/local/file.pdf", "name": "renamed.pdf"?}` — read from disk
+- `{"name": "x.bin", "content_base64": "..."}` — inline base64
+- `{"name": "x.txt", "content": "hello", "mime": "text/plain"?}` — inline text
+
+### Read a message and its attachments
+
+```json
+{
+  "action": "read",
+  "params": {"uid": "42", "folder": "INBOX", "include_attachments": true}
+}
+```
+
+### Download only specific attachments
+
+```json
+{
+  "action": "download_attachments",
+  "params": {"uid": "42", "filenames": ["report.pdf"]}
+}
+```
+
+### Send a calendar invite
+
+```json
+{
+  "action": "send_invite",
+  "params": {
+    "to": "guest@example.com",
+    "subject": "Kickoff",
+    "start": "2026-07-25 09:00",
+    "end":   "2026-07-25 10:00",
+    "location": "Zoom link here",
+    "description": "quarter review"
+  }
+}
+```
+
+Datetimes accept ISO 8601 (`2026-07-25T09:00:00-06:00`) or
+`YYYY-MM-DD HH:MM`. Naive times are assumed UTC.
+
+### Save a draft
+
+```json
+{"action": "save_draft", "params": {"subject": "todo", "text": "..."}}
+```
+
+### Search
+
+```json
+{"action": "search", "params": {"query": "invoice", "field": "SUBJECT"}}
+```
+
+### Pick an account (multi-account setup)
+
+Any action accepts an optional `account` param; omit it to use the first
+configured account:
+
+```json
+{"action": "send", "params": {"account": "work", "to": "...", "text": "..."}}
+```
+
+## Send gate (recommended when an agent has this tool)
+
+Prevent accidental sends by requiring a shared secret:
+
+```bash
+export EMAIL_SEND_CONFIRMATION_CODE=please-send
+```
+
+Every `send` / `send_invite` call must include `confirm: "please-send"` in
+params, or the server refuses.
+
+## Security notes
+
+* `.env` is git-ignored. Never commit it.
+* Prefer a **dedicated mailbox** (e.g. `mcp@yourdomain.com`) with a small quota.
+* If your provider supports **app passwords** (Gmail, Fastmail, iCloud), use one
+  instead of your primary password.
+* MCP env vars end up in `~/.claude.json` on your machine — treat that file
+  like a keychain.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cpanel_mail_mcp-0.2.0/README.md

@@ -0,0 +1,234 @@
+# cpanel-mail-mcp
+
+MCP server for IMAP/SMTP email accounts — works with cPanel, Gmail
+(app passwords), Outlook, Fastmail, iCloud, or any provider that speaks
+plain IMAP + SMTP.
+
+## Features
+
+* **Multi-account** — manage multiple email accounts from different providers
+* **Read, search, list** — full IMAP support with folder browsing
+* **Send emails** — plain text, HTML, or both (multipart/alternative)
+* **Attachments** — send via file path or base64-encoded inline data
+* **Download attachments** — extract attachments from received emails as base64
+* **Calendar invites** — send proper ICS invitations with Accept/Decline buttons
+* **Save to Sent** — automatically saves sent emails to the Sent folder via IMAP
+* **Optional send gate** — configurable confirmation code to prevent accidental sends
+* **International folders** — handles UTF-7 encoded folder names (German, etc.)
+* **Compact MCP surface** — one `email` tool with lazy action discovery to reduce
+  client context use
+
+## Install
+
+### With `uvx` (recommended, no venv setup)
+
+```bash
+claude mcp add cpanel-mail \
+  -e CPANEL_USER=you@example.com \
+  -e CPANEL_PASS='your_password' \
+  -e CPANEL_SMTP_HOST=mail.example.com \
+  -e CPANEL_IMAP_HOST=mail.example.com \
+  -- uvx cpanel-mail-mcp
+```
+
+### With `pipx`
+
+```bash
+pipx install cpanel-mail-mcp
+claude mcp add cpanel-mail \
+  -e CPANEL_USER=you@example.com -e CPANEL_PASS='...' \
+  -e CPANEL_SMTP_HOST=mail.example.com -e CPANEL_IMAP_HOST=mail.example.com \
+  -- cpanel-mail-mcp
+```
+
+### Development install (from a git checkout)
+
+```bash
+git clone https://github.com/rsauceda/cpanel-mail-mcp
+cd cpanel-mail-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+cp .env.example .env         # edit
+cpanel-mail-mcp              # runs the stdio server
+# or: python -m cpanel_mail_mcp
+```
+
+## Configuration
+
+Three ways, in priority order:
+
+### 1. `EMAIL_ACCOUNTS_JSON` (best for multi-account)
+
+```bash
+export EMAIL_ACCOUNTS_JSON='[
+  {"name":"work","user":"me@work.com","password":"...",
+   "smtp_host":"mail.work.com","imap_host":"mail.work.com",
+   "sent_folder":"INBOX.Sent"},
+  {"name":"gmail","user":"me@gmail.com","password":"app_pass",
+   "smtp_host":"smtp.gmail.com","smtp_port":587,
+   "imap_host":"imap.gmail.com","sent_folder":"[Gmail]/Sent Mail"}
+]'
+```
+
+### 2. `EMAIL_ACCOUNTS_FILE`
+
+Point to a JSON file with the same shape.
+
+### 3. Legacy single-account (`CPANEL_*`)
+
+Backwards compatible with 0.1.x installs. See [`.env.example`](.env.example).
+
+### Account fields
+
+| field           | required | default   |
+|-----------------|----------|-----------|
+| `name`          | no       | `user`    |
+| `user`          | **yes**  | —         |
+| `password`      | **yes**  | —         |
+| `smtp_host`     | **yes**  | —         |
+| `smtp_port`     | no       | `465`     |
+| `imap_host`     | **yes**  | —         |
+| `imap_port`     | no       | `993`     |
+| `sent_folder`   | no       | `Sent`    |
+| `drafts_folder` | no       | `Drafts`  |
+| `save_to_sent`  | no       | `true`    |
+| `from_name`     | no       | —         |
+
+### Loading a dev `.env`
+
+The server auto-loads `.env` from the current working directory. Point it
+elsewhere with:
+
+```bash
+export EMAIL_ENV_FILE=/absolute/path/to/.env
+```
+
+## Usage — the `email` tool
+
+The server exposes **one** MCP tool named `email`. Call it with an `action`
+string and a `params` dict. Discover actions with `action='help'` — the
+default when `action` is omitted:
+
+```json
+{ "action": "help" }
+```
+
+### Actions at a glance
+
+| action                | purpose                                          |
+|-----------------------|--------------------------------------------------|
+| `help`                | list all actions and their signatures            |
+| `list_accounts`       | see configured accounts (no secrets returned)    |
+| `list_folders`        | list IMAP folders (UTF-7 decoded)                |
+| `list_recent`         | last N messages of a folder                      |
+| `search`              | IMAP search by FROM/TO/SUBJECT/BODY/TEXT         |
+| `read`                | read a message by UID (optionally with attachments) |
+| `download_attachments`| fetch attachments as base64                       |
+| `send`                | send an email (text/HTML/attachments)             |
+| `save_draft`          | append a draft to the account's Drafts folder     |
+| `send_invite`         | send an ICS calendar invite                       |
+
+### Send an email with an attachment
+
+```json
+{
+  "action": "send",
+  "params": {
+    "to": "someone@example.com",
+    "subject": "Report",
+    "text": "See attached.",
+    "html": "<p>See <b>attached</b>.</p>",
+    "attachments": [
+      {"path": "/tmp/report.pdf"},
+      {"name": "note.txt", "content": "hi from inline"}
+    ]
+  }
+}
+```
+
+Attachment shapes accepted:
+- `{"path": "/local/file.pdf", "name": "renamed.pdf"?}` — read from disk
+- `{"name": "x.bin", "content_base64": "..."}` — inline base64
+- `{"name": "x.txt", "content": "hello", "mime": "text/plain"?}` — inline text
+
+### Read a message and its attachments
+
+```json
+{
+  "action": "read",
+  "params": {"uid": "42", "folder": "INBOX", "include_attachments": true}
+}
+```
+
+### Download only specific attachments
+
+```json
+{
+  "action": "download_attachments",
+  "params": {"uid": "42", "filenames": ["report.pdf"]}
+}
+```
+
+### Send a calendar invite
+
+```json
+{
+  "action": "send_invite",
+  "params": {
+    "to": "guest@example.com",
+    "subject": "Kickoff",
+    "start": "2026-07-25 09:00",
+    "end":   "2026-07-25 10:00",
+    "location": "Zoom link here",
+    "description": "quarter review"
+  }
+}
+```
+
+Datetimes accept ISO 8601 (`2026-07-25T09:00:00-06:00`) or
+`YYYY-MM-DD HH:MM`. Naive times are assumed UTC.
+
+### Save a draft
+
+```json
+{"action": "save_draft", "params": {"subject": "todo", "text": "..."}}
+```
+
+### Search
+
+```json
+{"action": "search", "params": {"query": "invoice", "field": "SUBJECT"}}
+```
+
+### Pick an account (multi-account setup)
+
+Any action accepts an optional `account` param; omit it to use the first
+configured account:
+
+```json
+{"action": "send", "params": {"account": "work", "to": "...", "text": "..."}}
+```
+
+## Send gate (recommended when an agent has this tool)
+
+Prevent accidental sends by requiring a shared secret:
+
+```bash
+export EMAIL_SEND_CONFIRMATION_CODE=please-send
+```
+
+Every `send` / `send_invite` call must include `confirm: "please-send"` in
+params, or the server refuses.
+
+## Security notes
+
+* `.env` is git-ignored. Never commit it.
+* Prefer a **dedicated mailbox** (e.g. `mcp@yourdomain.com`) with a small quota.
+* If your provider supports **app passwords** (Gmail, Fastmail, iCloud), use one
+  instead of your primary password.
+* MCP env vars end up in `~/.claude.json` on your machine — treat that file
+  like a keychain.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cpanel_mail_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "cpanel-mail-mcp"
+version = "0.2.0"
+description = "MCP server for IMAP/SMTP email — multi-account, attachments, ICS calendar invites, drafts, Save-to-Sent."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Rodrigo Sauceda", email = "rodrigo.sauceda@gmail.com" }]
+keywords = ["mcp", "email", "imap", "smtp", "cpanel", "calendar", "ics", "attachments"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+]
+dependencies = [
+    "mcp[cli]>=1.2.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rsauceda/cpanel-mail-mcp"
+Repository = "https://github.com/rsauceda/cpanel-mail-mcp"
+Issues = "https://github.com/rsauceda/cpanel-mail-mcp/issues"
+
+[project.scripts]
+cpanel-mail-mcp = "cpanel_mail_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

cpanel_mail_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cpanel_mail_mcp-0.2.0/src/cpanel_mail_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""cpanel-mail-mcp — MCP server for IMAP/SMTP email accounts."""
+from .server import main, mcp
+
+__version__ = "0.2.0"
+__all__ = ["main", "mcp", "__version__"]

cpanel_mail_mcp-0.2.0/src/cpanel_mail_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

cpanel_mail_mcp-0.2.0/src/cpanel_mail_mcp/accounts.py

@@ -0,0 +1,103 @@
+"""Account discovery from environment.
+
+Priority:
+  1. `EMAIL_ACCOUNTS_JSON`  — JSON array of account dicts.
+  2. `EMAIL_ACCOUNTS_FILE`  — path to a JSON file with the same array.
+  3. Legacy `CPANEL_USER`/`CPANEL_PASS`/... single account.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Account:
+    name: str
+    user: str
+    password: str
+    smtp_host: str
+    smtp_port: int
+    imap_host: str
+    imap_port: int
+    sent_folder: str
+    drafts_folder: str
+    save_to_sent: bool
+    from_name: str | None
+
+
+def _from_dict(d: dict) -> Account:
+    if not d.get("user") or not d.get("password"):
+        raise ValueError(f"account {d.get('name')!r} missing user/password")
+    host = d.get("host") or ""
+    return Account(
+        name=str(d.get("name") or d["user"]),
+        user=d["user"],
+        password=d["password"],
+        smtp_host=d.get("smtp_host") or host,
+        smtp_port=int(d.get("smtp_port", 465)),
+        imap_host=d.get("imap_host") or host,
+        imap_port=int(d.get("imap_port", 993)),
+        sent_folder=d.get("sent_folder", "Sent"),
+        drafts_folder=d.get("drafts_folder", "Drafts"),
+        save_to_sent=bool(d.get("save_to_sent", True)),
+        from_name=d.get("from_name"),
+    )
+
+
+def _legacy() -> Account | None:
+    user = os.environ.get("CPANEL_USER")
+    pw = os.environ.get("CPANEL_PASS")
+    if not user or not pw:
+        return None
+    return _from_dict(
+        {
+            "name": os.environ.get("CPANEL_ACCOUNT_NAME", "default"),
+            "user": user,
+            "password": pw,
+            "smtp_host": os.environ.get("CPANEL_SMTP_HOST", ""),
+            "smtp_port": int(os.environ.get("CPANEL_SMTP_PORT", "465")),
+            "imap_host": os.environ.get("CPANEL_IMAP_HOST", ""),
+            "imap_port": int(os.environ.get("CPANEL_IMAP_PORT", "993")),
+            "sent_folder": os.environ.get("CPANEL_SENT_FOLDER", "INBOX.Sent"),
+            "drafts_folder": os.environ.get("CPANEL_DRAFTS_FOLDER", "INBOX.Drafts"),
+            "save_to_sent": os.environ.get("CPANEL_SAVE_TO_SENT", "true").lower() != "false",
+            "from_name": os.environ.get("CPANEL_FROM_NAME"),
+        }
+    )
+
+
+def load_accounts() -> dict[str, Account]:
+    accts: list[Account] = []
+    raw = os.environ.get("EMAIL_ACCOUNTS_JSON")
+    if raw:
+        accts.extend(_from_dict(d) for d in json.loads(raw))
+    else:
+        path = os.environ.get("EMAIL_ACCOUNTS_FILE")
+        if path:
+            accts.extend(_from_dict(d) for d in json.loads(Path(path).read_text()))
+    if not accts:
+        legacy = _legacy()
+        if legacy:
+            accts.append(legacy)
+    if not accts:
+        raise RuntimeError(
+            "No email accounts configured. Set EMAIL_ACCOUNTS_JSON, "
+            "EMAIL_ACCOUNTS_FILE, or the legacy CPANEL_USER/CPANEL_PASS/... env vars."
+        )
+    out: dict[str, Account] = {}
+    for a in accts:
+        if a.name in out:
+            raise ValueError(f"duplicate account name: {a.name!r}")
+        out[a.name] = a
+    return out
+
+
+def get_account(accounts: dict[str, Account], name: str | None) -> Account:
+    if not name:
+        return next(iter(accounts.values()))
+    if name in accounts:
+        return accounts[name]
+    raise ValueError(f"unknown account {name!r}. Available: {list(accounts)}")