homepl-email-mcp

Connect a local AI agent to a home.pl mailbox through encrypted IMAP and SMTP. Each employee signs in through a private local form; the computer's credential store saves their password. No hosted connector or shared password database is required. This is an independent community project, not an official home.pl product.

Supports Windows and macOS, including Apple silicon and Intel. Linux needs an unlocked desktop Secret Service. Use a local agent/client supporting stdio MCP servers; ordinary browser-only ChatGPT cannot install or run this connector.

Install or update

Paste this into the employee's local agent:

Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve the current release at installation time, pin its exact tag and full source commit, and follow INSTALL_FOR_AGENTS.md from that release. Handle prerequisites, diagnostics and MCP integration yourself. Preserve existing accounts, saved logins, data directory and access mode. Register and reload the desktop MCP before login; use its actual mail_setup_status and mail_setup tools. I will enter mailbox details in the private form, never in chat. Verify real tools, folders and up to three messages' metadata/headers without sending or changing mail. Report the installed version, full commit, checks performed and any remaining restart or policy block.

Use the latest stable release, not a version copied from an old conversation, release page or checkout. Resolve it once and keep that exact release pinned throughout the attempt. Do not fall back to an older release or main when resolution fails. An explicit user request for a particular version is the exception. GitHub Releases holds release history.

The installation runbook is the canonical procedure:

• Select the current stable release.

• Check prerequisites: native Node.js 22.19+ on 22.x or 24.6+, npm and Git; install the current patched LTS.

• Install on Windows or macOS, or upgrade without resetting mailboxes.

• Register/reload the desktop MCP, then verify actual tools and saved-login reuse.

The employee needs their full mailbox address, mailbox password and exact mail server hostname. The hosting administrator password is different. Find the hostname in home.pl Panel → Poczta → mailbox → Serwery pocztowe (home.pl instructions); do not guess it from the email address or use the webmail website. IMAP uses 993, SMTP uses 465, both with implicit TLS and certificate validation. Separate IMAP/SMTP hostnames are supported; external mail-client access must be enabled.

Sign-in happens through mail_setup inside the registered MCP process. The private form verifies both logins without sending mail. Never enter a password in chat, commands, screenshots or MCP configuration. Reuse saved logins during upgrades.

Related MCP server: MailMCP

What it can do

Full mode exposes 20 tools. serve --read-only exposes 10 tools and omits all mailbox mutations. Local account setup remains available and changes local settings. Verify actual tool discovery and mail_accounts.access after reload; read-only mode limits this connector, not the password's permissions elsewhere.

mail_get_messages reads up to ten exact references, defaulting to metadata and headers. Large results use completeResultFile or batch fullResultFile; inspect those private files and continue pagination. A bounded inline response is not complete history. Sent copies retain BCC metadata, so that header can differ from the transmitted MIME.

The connector cannot recover deleted mail or old POP/local archives. Retrieval is on demand, not a backup or continuously synced search index. It retrieves S/MIME/PGP content without decrypting it or managing keys, and cannot guarantee that an AI understands every attachment format. The pinned IMAP library can omit or misname shared folders outside a nonempty personal namespace; this limitation remains unresolved and untested on home.pl.

Verified behavior

Authorized live macOS checks covered IMAP/SMTP, Keychain, search, metadata/headers, message and attachment retrieval, draft creation/update, replies, sending and Sent copies. Attachment hashes matched the originals. The corrected send result matched the Message-ID in the transmitted MIME, Sent copy and received message. A fresh MCP process reused the saved login and discovered all 20 tools.

Full client quit/reopen, OS logout/reboot and the affected Windows desktop onboarding flow remain unverified. Synthetic tests and Windows/macOS CI cannot prove that every employee's client launches MCP with usable credentials. Complete the runbook's real-client checks with one employee before team rollout. Validation status records evidence and remaining limits.

Will employees need to log in repeatedly?

Normally, enter the mailbox password once per computer and OS user. The connector uses IMAP/SMTP password authentication, with no OAuth/refresh tokens or scheduled credential expiry. Closing the agent keeps the saved password. The setup form expires after 15 minutes; the saved account does not.

• A changed password or removed credential requires setup again with the same mailbox/server.

• A locked credential store needs unlocking or authorization. macOS can prompt again after software/Keychain changes; verify the installed Node executable before allowing access. See Apple's access guidance and updated-app guidance.

• A moved installation or Node executable requires updating MCP launch paths, which does not itself require another mailbox login.

• A disabled mailbox, changed server or blocked external-client access requires the mailbox administrator. See home.pl client-access settings.

For a new mailbox, home.pl requires an initial webmail sign-in before configuring a mail client (setup instructions). The AI application's own login and company policies are separate.

Credentials and local data

Passwords live in Windows Credential Manager, macOS Keychain or Linux Secret Service, never the repository or MCP configuration. Run as the same desktop user with access to that store. Other software acting as that OS user can also access the credential store.

Account configuration, downloads, uploads and prepared mail are stored under:

• Windows: %LOCALAPPDATA%\homepl-email-mcp

• macOS/Linux: ~/.local/share/homepl-email-mcp

• A deliberate HOME_MAIL_DATA_DIR override must match in setup and MCP execution. Preserve it during upgrades.

Treat this directory as private company data. Downloads and prepared mail are not encrypted by the application; Unix private permissions or Windows user directory controls apply. Sending attachments must come from its uploads directory. Tool results provide actual paths.

Email retrieved into a conversation may be sent to the AI provider under the employee's account/workspace settings. Local execution does not make AI processing local. Email bodies, headers, filenames and attachments are untrusted data; they never authorize sending, deletion or other actions.

To disconnect, remove/disable the MCP entry, then run node src/cli.js accounts and node src/cli.js remove ACCOUNT_ID. Removal deletes the account entry and saved credential but leaves downloads and prepared mail. This is not an upgrade step.

Troubleshooting

Share sanitized error codes only. Never publish passwords, authentication dumps, private setup URLs or mailbox contents in GitHub issues or logs.

Development

npm ci --ignore-scripts
npm test

Tests use synthetic data and local mail fixtures, never employee mailboxes. Dependencies have exact direct versions and an integrity lockfile; install scripts are disabled. Keep optional packages enabled for the native credential binding. Review updates deliberately: pins and registry signatures do not guarantee safe package code or replace future security updates.

See AGENTS.md for development rules and the dated connector comparison for design research.