mailbox

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Self-hosted REST API and web UI for all your mailboxes (IMAP, JMAP, POP3, Gmail, Microsoft 365, Outlook.com), with a Python client and an MCP server so AI agents read, sort, draft and send mail, only within the rights, folders and send limits you grant. Change feed, signed webhooks, audit.

README.md

Mailbox

CI
Coverage
License
Python

PyPI benethos-mailbox-service
Container benethos-mailbox-service

PyPI benethos-mailbox-mcp
Container benethos-mailbox-mcp

PyPI benethos-mailbox-client

PyPI benethos-mailbox-common

Sponsor
PayPal

benethos-mailbox-mcp on Glama

One REST API for all your mailboxes, whichever provider they are at, a
Python client for it and an MCP server on top. Scripts, tools and AI
agents work with your mail through one door you control.

Status: beta, version 0.8.0. Usable with real accounts. A breaking
change of the API or the configuration is announced in the changelog.
Stored data is carried forward by migrations.

Contents

What it is for

Most people and small companies have more than one mail account: a
personal address at GMX or web.de, a company mailbox at Microsoft 365, an
info@ address at some hoster, maybe a Gmail account. Each speaks its own
dialect: IMAP here, Microsoft Graph there. Every tool that wants to work
with mail has to learn all of them and has to be given the passwords.

Mailbox turns that around. It has four packages. mailbox-service runs on
your own machine or server and holds the connections to all accounts.
Everything else talks to that service only, through one REST API that
looks the same for every provider. mailbox-client is the Python
client of that API, for scripts and apps. mailbox-mcp, the MCP
server, builds on the client and opens the service to AI agents.
mailbox-common holds what the service and the MCP server share. The
service decides who may do what. A script, an app or an AI agent gets
a token of its own. That token opens exactly the accounts and
operations it was given, nothing more.

AI agents reach mailbox-mcp over MCP, scripts and apps use mailbox-client or call the REST API themselves, and mailbox-mcp builds on mailbox-client. mailbox-client calls the REST API of mailbox-service, people use its configuration UI in the browser, and its signed webhooks report changes to your systems. mailbox-service, on your own server, connects to the mail accounts over IMAP and SMTP, Microsoft Graph, JMAP, POP3 and the Gmail API.

That makes a few things simple that are hard otherwise.

Working with an AI agent in your mail

Through the MCP server, Claude or another AI agent works with every
account you gave it. A few requests it handles today:

  • "What came in since last night?"
  • "Move every invoice from Company XY to the folder Accounting."
  • "Forward today's invoices to our tax advisor."
  • "Show me all mail from Company XY between the 1st and the 15th of
    September."
  • "Which mails with attachments came this week? Read the invoice and tell
    me the amount and the due date."
  • "Sum up the mails about the offer and write a draft reply."
  • "Mark last week's newsletters as read and move them to the archive."

Its rights decide whether it may send on its own or only leave drafts
for a person to send. A grant can also name the recipients it may write
to, such as the tax advisor's address alone, and how many mails it may
send a day. A mail to anyone else is refused. It can keep the agent to
some folders, such as the invoices, and end after a week.

More uses

  • Controlled access. A bookkeeping tool reads the invoice folder of
    one account and nothing else. It may neither send nor delete, and it
    never sees a mail password, only its own token.
  • Automation across accounts. A script files invoices, archives
    newsletters and forwards order confirmations. It works the same way for
    GMX, Microsoft 365 and your own mail server.
  • Sending with guard rails. A newsletter job sends from info@, to a
    fixed list of recipients, at most a few times a day.
  • React instead of polling. Signed webhooks tell your own system
    about new mail, a ticket tool or an internal dashboard for example.
  • Traceable. Every send is recorded in the audit: by whom, with
    which token, to whom and when. So is every sign-in and every change
    to users, tokens, roles, accounts and webhooks.
  • One inbox for your own tools. A dashboard or a small internal app
    lists, searches and answers mail from every account with one client.
  • Self-hosted. The service stores the credentials encrypted. Mail
    goes straight from the provider to you, never through a third party's
    cloud.

What it can do today

  • Accounts: IMAP with SMTP for sending, set up from the address alone
    (autodiscovery), JMAP servers such as Fastmail and Stalwart, POP3
    for mailboxes without IMAP (the inbox only), Microsoft accounts
    (Outlook.com, Microsoft 365) over Microsoft Graph with OAuth sign-in,
    and Gmail over the Gmail API.
    Credentials are encrypted (AES-256-GCM) under a master key kept
    outside the database.
  • Reading: folders, lists and search, one account or all at once,
    conversations across folders, messages as text and HTML, attachments,
    the raw source, and the receiving server's check of the sender's
    domain (sender_check). Message ids stay
    the same when a message moves, kept by a background sync. A link to an
    attachment lets another service fetch the file once, without a token.
  • Writing: read state, stars and keywords, moving, deleting,
    folders, drafts, and sending with reply, reply to all and forward. A retried send is not sent twice
    (Idempotency-Key).
  • Changes: a change feed names each message created, changed or
    deleted since a point you keep, in IMAP, JMAP, POP3, Microsoft and
    Gmail accounts, flags set in other mail clients included where the IMAP
    server offers CONDSTORE. Webhooks post the same events, signed, to a URL of your
    choice, a host in your local network included.
  • Users and rights: users, roles and grants per account and per
    operation, down to folders, grants that expire, API tokens, limits on
    sending (allowed recipients, sends per day), an audit of every send
    and an audit of administration, and a second factor for the UI
    sign-in: an authenticator app or a passkey.
  • MCP server: reads, sorts, writes drafts, sends and tells what is
    new, over stdio or streamable HTTP, offering only the mail tools its
    token may use, server_status always, and following its rights while
    it runs. Mail content reaches
    the model marked as foreign text.
  • Configuration UI in the browser under /ui: accounts, users,
    rights, tokens, reading and writing mail, the send audit, webhooks,
    the status of accounts and sync, the audit of administration, the
    service log.
  • Operation: encrypted backup and restore, container images, compose
    files for operation with HTTPS through Caddy and MCP server instances.

What comes next, and in which order, is in
docs/ROADMAP.md.

Providers

Provider Connected via Credential State
GMX, web.de, T-Online, Yahoo, AOL, iCloud, Posteo, mailbox.org, IONOS, Strato, own mail servers IMAP + SMTP app password available
Microsoft 365, Outlook.com Microsoft Graph OAuth, through the project's app or your own (setup) available
Proton Mail IMAP + SMTP through Proton Mail Bridge Bridge password IMAP, not tested
Gmail / Google Workspace Gmail API, or IMAP + SMTP OAuth, with your own Google Cloud client (setup), or an app password available
Fastmail, Stalwart, other JMAP servers JMAP API token or password available
legacy mailboxes without IMAP POP3 + SMTP: the inbox only, no folders, no read state, no search password available

Not supportable: Tuta, which offers no IMAP and no API. Details per
provider in the concept, section 5.3.

The four packages

Package What it is Runs Read more
mailbox-service the service: REST API, configuration UI, users and rights, accounts, encrypted credentials, provider adapters, background sync permanently packages/mailbox-service
mailbox-client the Python client of the REST API, async and sync inside your own code packages/mailbox-client
mailbox-mcp the MCP server, on top of mailbox-client per client over stdio, or as a server over HTTP packages/mailbox-mcp
mailbox-common what the service and the MCP server share installed with them packages/mailbox-common

A release publishes all four to PyPI under the same version, as
benethos-mailbox-service, benethos-mailbox-client,
benethos-mailbox-mcp and benethos-mailbox-common, and the service
and the MCP server as container
images on ghcr.io. The MCP server is listed in the official MCP
Registry as io.github.benethos-hub/benethos-mailbox-mcp, and every
release carries it as a Claude Desktop extension,
benethos-mailbox-mcp.mcpb. Each package has its own README. It
explains how to install, start and configure it, for the service and
the MCP server with the container image and the compose file.

The MCP server and the service must have the same version to work
together. Update both at once. The MCP server's tool server_status
shows the service's version and whether it matches its own.

Tools

The tools of the MCP server. Each is offered only to a token with the
right it needs. What each takes and answers, and the hints it carries
for clients: packages/mailbox-mcp.

Tool Needs What it does
list_accounts – the accounts and what may be done on each
list_folders mail.read the folders of an account, with their roles and counts
search_messages mail.read finds mail in one account, several or all
get_message mail.read one mail as plain text, with its attachments listed
get_thread mail.read a conversation across folders
whats_new mail.read mail created, changed or deleted since an earlier call
get_attachment mail.read an attachment: images, PDF pages as images, text
share_attachment mail.share a link another service fetches an attachment with, once
update_messages mail.write read state, star, move, keywords, labels, trash
create_folder mail.write a new folder
update_folder mail.write renames or moves a folder
list_drafts drafts the drafts of an account
create_draft drafts a draft, also as a reply or a forward
update_draft drafts replaces a draft
delete_draft drafts deletes a draft
send_message send sends a mail at once
send_draft send sends a stored draft
server_status – what runs, and whether the service answers

Getting started

  1. Start the service and create the first user:
    packages/mailbox-service.
  2. Open http://127.0.0.1:8080/ui, sign in as admin with the
    one-time password, choose a password of your own and connect your
    accounts.
  3. Give your scripts or your AI agent a user with the rights they need
    and a token
    (step by step),
    and for an agent, add the MCP server to it. Claude Desktop installs
    it as an extension from the release, other clients start it with
    uvx: packages/mailbox-mcp.

Documentation

Development

One uv workspace, one lockfile, four distributions.

uv sync
uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run mypy

The tests run offline. CI runs these checks too, most of them as the
organisation's reusable workflows. It also installs the packages on the
lowest versions their pyproject.toml allows and runs the tests there,
checks those versions and every version in uv.lock against OSV for
known vulnerabilities, and checks the brand assets in assets/brand/.
Every one of these checks has to pass before a change reaches main.
A further job opens the configuration UI in Chrome, Firefox and WebKit
and checks what only a browser shows: the page of a sign-in with a code
goes on by itself, and no page breaks the content security policy.

CodeQL reads the code and the workflows on every change and once a week,
hadolint the Dockerfiles on every change. Both file what they find under
Security, Code scanning. A merge does not wait for them.

A separate workflow runs once a day and after each run of the publishing
workflow, and passes or stops nothing. It keeps one issue with what the
project pins and what is newer: packages, vulnerabilities, images, actions
and the JavaScript the UI ships. A second issue opens when the newest
versions the ranges in pyproject.toml allow break the tests or
tests/installed_check.py, or when a published package no longer installs
or starts from PyPI. An install without the lockfile, such as uvx or
pip install, gets those versions, so this can change on any day without a
release here. That check sees neither a real mailbox nor the MCP server in
front of the real service.

Manual checks against real test accounts live in live/ and are
described in docs/LIVE.md. The working rules for this
repository are in CLAUDE.md.

Licence

MIT, see LICENSE.

Yorumlar (0)

Sonuc bulunamadi