ox-mcp
ox-mcp
An MCP server for Open-Xchange and standards-based mail platforms — read & search email, send & reply, manage server-side filters, calendar events and invitations, contacts, and other people's availability (free/busy), across one or many accounts.
It speaks standard IMAP + SMTP + ManageSieve + CalDAV + CardDAV with RFC 6638 free/busy, so it works with any Open-Xchange deployment or standards-compliant host. Authenticate with your email + app password (the same credential DAVx5 uses) or OAuth2/OIDC.
No affiliation with Open-Xchange.
Install / run
npx -y @rheopyrin/ox-mcp
# or with a custom config location:
npx -y @rheopyrin/ox-mcp --config /path/to/config.jsonMCP client config (Claude Desktop / Claude Code):
{
"mcpServers": {
"ox": {
"command": "npx",
"args": ["-y", "@rheopyrin/ox-mcp"],
"env": {
"OX_MCP_MAIL_SERVER": "mail.example.com",
"OX_MCP_MAIL_USER": "you@yourdomain.com",
"OX_MCP_MAIL_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
"OX_MCP_CALDAV_SERVER": "dav.example.com",
"OX_MCP_CALDAV_USER": "you@yourdomain.com",
"OX_MCP_CALDAV_APP_PASSWORD": "yyyy-yyyy-yyyy-yyyy"
}
}
}
}On first run (without --config) it creates ~/.ox-mcp/config.json (permissions 0600) with every feature flag listed — reads enabled, writes disabled — and empty hosts for you to fill in.
--config
--config <file> (or env OX_MCP_CONFIG; the flag wins) loads an explicit config file instead of ~/.ox-mcp/config.json. The file must exist — nothing is auto-created when the override is used.
Related MCP server: zimbra-mcp
Tools
Tools are grouped by protocol domain. A group's tools appear only when enabled, and the group's server host must be configured (see Validation).
Group | Read (enabled by default) | Write (disabled by default) |
|
|
|
|
|
|
|
|
|
meta |
| — |
Every tool (except
list_servers) accepts an optionalserverargument to target a specific account. A tool is hidden from the tool list unless its flag is enabled for at least one account.email_searchsearches all folders by default; passfolderto narrow it. On theox-apitransport,body/textmatch only the subject and addresses of recent messages — usetransport: "imap"for true full-text search.email_mark_spam/email_archivefind the Junk/Archive folder via IMAP special-use attributes, with name-based fallbacks.email_reply/email_reply_allpreserve threading (In-Reply-To/References) and exclude your own address from reply-all recipients.The three RSVP tools (
calendar_accept_event/calendar_decline_event/calendar_tentative_event) share one feature flag:respondEvent(calDav section). They rewrite yourPARTSTATon the invitation; the server notifies the organizer.contact_findsearches contacts server-side (CardDAVaddressbook-query, RFC 6352) with automatic fallback to client-side filtering;fieldsnarrows the match toname/email/phone/org(default name + email). Handy for resolving a name to an email beforecalendar_free_busy.contact_listis plain enumeration.
Mail filters
email_filter_create / email_filter_update manage server-side sieve filters over ManageSieve (port 4190, STARTTLS; requires basic/app-password auth). Rules support conditions on from/to/subject/any header (AND or OR) and actions fileinto (move to folder), discard, markRead, redirect.
Backend depends on
mail.transport: with ox-api (default), filters go through the OXmailfilter/v2module and operate on the account's real webmail rules (rules with tests/actions beyond this model are listed read-only asother). With imap, ox-mcp manages its own sieve script over ManageSieve (port 4190) and activates it — filters from other scripts become inactive while it is active.
Configuration: per-protocol sections
Each account is made of up to three self-contained sections — mail, calDav, cardDav — each with its own server, auth (incl. its own login user), and features. This matches servers (like Open-Xchange) that scope app passwords per protocol: your Mail password, CalDAV password, and CardDAV password can all differ.
{
"defaultServer": "default",
"timeoutSeconds": 300, // optional; request timeout, default 300
"servers": {
"default": {
"mail": {
"server": "webmail.example.com", // OX HTTP API host (default transport)
"transport": "ox-api", // optional; "imap" for direct IMAP/SMTP
"imap": { "host": "imap.example.com", "port": 993 }, // optional overrides
"smtp": { "host": "smtp.example.com", "port": 587, "secure": false }, // secure optional; 993/465 = TLS, else STARTTLS
"auth": { "type": "basic", "user": "me@example.com", "appPassword": "mail-scoped-pw" },
"features": { "search": true, "send": false /* per-tool flags */ }
},
"calDav": {
"server": "dav.example.com",
"auth": { "type": "basic", "user": "me@example.com", "appPassword": "caldav-scoped-pw" },
"features": { "respondEvent": false /* … */ }
},
"cardDav": {
"server": "dav.example.com",
"auth": { "type": "basic", "user": "me@example.com", "appPassword": "carddav-scoped-pw" }
}
}
}
}A section you don't configure = its tools are disabled. A calDav-only config is perfectly valid.
mail.transportis optional and defaults to"ox-api"— the Open-Xchange HTTP API (the webmail backend,https://<server>/appsuite/api). OX deployments validate app passwords at this middleware, so it works even where raw IMAP rejects them;serveris the webmail host. Filter tools use the OXmailfilter/v2module — they list and edit the account's actual webmail rules. Caveat: search matches subject/addresses (not full bodies).Set
transport: "imap"for direct IMAP/SMTP against generic (non-OX) mail hosts — thenserveris the mail host, with optional splitimap/smtpendpoints.enabled: falseon a section is a config master switch for all its tools.There is no global features block — flags live only inside sections (env vars remain global).
Feature flags
Resolution precedence — env always beats config, first defined wins:
per-account env, tool —
OX_MCP_<ID>_ENABLE_EMAIL_SENDper-account env, group —
OX_MCP_<ID>_ENABLE_MAILglobal env, tool —
OX_MCP_ENABLE_EMAIL_SENDglobal env, group —
OX_MCP_ENABLE_MAIL/_CALDAV/_CARDDAVsection config, tool —
servers.<id>.mail.features.sendsection config, master —
servers.<id>.mail.enableddefault —
truefor reads,falsefor writes
# enable sending on all accounts
OX_MCP_ENABLE_EMAIL_SEND=true
# turn off the whole calendar section
OX_MCP_ENABLE_CALDAV=false
# enable event creation only on the "work" account
OX_MCP_WORK_ENABLE_CALENDAR_CREATE_EVENT=true
# enable all three RSVP tools at once
OX_MCP_ENABLE_CALENDAR_RESPOND_EVENT=trueBooleans accept true/1/yes/on and false/0/no/off.
Connection & credentials (env)
Every section field is settable via env: OX_MCP_[ID_]<SECTION>_<FIELD> with SECTION ∈ MAIL | CALDAV | CARDDAV. The default account uses the non-indexed form.
Env var | Meaning |
| section host |
| section login user |
| section app password (basic auth) |
| mail transport overrides (Gmail-style split hosts) |
| force TLS ( |
| per-section OAuth/OIDC fields |
| request timeout for all HTTP/IMAP/SMTP operations (default 300) |
Default ports: IMAP 993, SMTP 465, DAV 443, ManageSieve 4190. TLS mode derives from the port (993/465 implicit TLS; 143/587 STARTTLS) unless secure is set explicitly.
Validation
Configuration is validated strictly at startup: every present section with enabled tools must have a server (or split imap/smtp hosts for mail) and a login user, or the server exits with an error naming the exact field. Accounts with zero sections error too. Absent sections are simply disabled — no error.
Authentication types
basic (app password) is the default. Other Open-Xchange-aligned mechanisms are supported per section via auth.type / OX_MCP_[ID_]<SECTION>_AUTH_TYPE:
Type | Extra fields (env: |
|
|
|
|
|
|
|
|
|
|
Tokens are cached and refreshed automatically. Note: mail filters (ManageSieve) require basic auth.
Multiple accounts
OX_MCP_ACCOUNTS=work,personal
OX_MCP_WORK_MAIL_SERVER=mail.work.com
OX_MCP_WORK_MAIL_USER=me@work.com
OX_MCP_WORK_MAIL_APP_PASSWORD=...
OX_MCP_PERSONAL_CALDAV_SERVER=dav.personal.com
OX_MCP_PERSONAL_CALDAV_USER=me@personal.com
OX_MCP_PERSONAL_CALDAV_APP_PASSWORD=...
OX_MCP_DEFAULT_SERVER=workOr define them in ~/.ox-mcp/config.json under servers (keyed by id). list_servers shows what's configured (never secrets); env values override config field-by-field. Feature flags can differ per account (e.g. sending enabled only on work).
Free/busy caveat
calendar_free_busy returns availability windows only (busy/free), via the CalDAV scheduling outbox — no calendar sharing needed. It does not reveal event details, and requires the server to advertise a schedule-outbox-URL. To read a colleague's full calendar, they must share it with your account; shared calendars then appear in calendar_list / calendar_list_events.
Docker
docker build -t ox-mcp .
docker run -i --rm \
-e OX_MCP_MAIL_SERVER=mail.example.com \
-e OX_MCP_MAIL_USER=you@yourdomain.com \
-e OX_MCP_MAIL_APP_PASSWORD=xxxx \
ox-mcpDevelopment
npm install
npm run dev # run from source
npm test # vitest
npm run test:coverage
npm run build # bundle to dist/ (tsup)License
MIT
Available Tools
33 toolscalendar_accept_eventAccept event invitationA
Accept a calendar event invitation as this account (sets your PARTSTAT to ACCEPTED; the server notifies the organizer).
Inputs: calendar (required), objectUrl (required), server.
calendar_create_eventCreate calendar eventC
Create a calendar event (VEVENT) in a calendar.
Inputs: end (required), start (required), summary (required), calendar (required), +5 more.
calendar_decline_eventDecline event invitationA
Decline a calendar event invitation as this account (sets your PARTSTAT to DECLINED; the server notifies the organizer).
Inputs: calendar (required), objectUrl (required), server.
calendar_delete_eventDelete calendar eventBDestructive
Delete a calendar event by its object URL.
Inputs: objectUrl (required), etag, server.
calendar_free_busyGet free/busyARead-only
Query attendees' availability (busy/free windows only) via the CalDAV scheduling outbox. No calendar sharing required.
Inputs: end (required), start (required), attendees (required), server.
calendar_listList calendarsARead-only
List CalDAV calendars (own and any shared with the account).
Inputs: server.
calendar_list_eventsList calendar eventsBRead-only
List events in a calendar within a time range.
Inputs: end (required), start (required), calendar (required), server.
calendar_tentative_eventTentatively accept event invitationA
Tentatively accept a calendar event invitation as this account (sets your PARTSTAT to TENTATIVE; the server notifies the organizer).
Inputs: calendar (required), objectUrl (required), server.
calendar_update_eventUpdate calendar eventB
Replace an existing calendar event by its object URL.
Inputs: end (required), start (required), summary (required), objectUrl (required), +7 more.
contact_createCreate contactB
Create a CardDAV contact (vCard) in an address book.
Inputs: name (required), emails, phones, server, +2 more.
contact_findFind contactsARead-only
Search CardDAV contacts by a case-insensitive substring (server-side where supported). Useful for resolving a name to an email address, e.g. before calendar_free_busy.
Inputs: query (required), limit, fields, server, +1 more.
contact_listList contactsARead-only
List all CardDAV contacts. Reads all address books unless one is given. To search, use contact_find instead.
Inputs: server, addressBook.
email_archiveArchive emailB
Move an email to the account's archive folder (special-use aware).
Inputs: uid (required), folder, server.
email_create_folderCreate mail folderA
Create a new IMAP folder. Use the delimiter of the account (usually "/") for nesting, e.g. "Projects/Acme".
Inputs: path (required), server.
email_deleteDelete emailADestructive
Delete an email by UID (moves to Trash or expunges per server policy).
Inputs: uid (required), folder, server.
email_delete_folderDelete mail folderADestructive
Delete an IMAP folder. The folder and its messages are removed — this cannot be undone.
Inputs: path (required), server.
email_filter_createCreate mail filterA
Create a server-side mail filter (sieve). Note: ox-mcp manages its own sieve script and activates it.
Inputs: name (required), action (required), conditions (required), stop, +2 more.
email_filter_listList mail filtersARead-only
List server-side mail filters managed by ox-mcp (sieve).
Inputs: server.
email_filter_updateUpdate mail filterA
Replace an existing ox-mcp mail filter by id (see email_filter_list).
Inputs: id (required), name (required), action (required), conditions (required), +3 more.
email_flagFlag emailC
Flag or unflag (star/unstar) an email.
Inputs: uid (required), folder, server, flagged.
email_listList emailsBRead-only
List the most recent emails in a folder (newest first).
Inputs: limit, folder, server.
email_list_foldersList mail foldersCRead-only
List IMAP mailboxes/folders for an account.
Inputs: server.
email_mark_readMark email as readC
Mark an email as read (sets the \Seen flag).
Inputs: uid (required), folder, server.
email_mark_spamMark as spamA
Move an email to the account's spam/junk folder (special-use aware).
Inputs: uid (required), folder, server.
email_mark_unreadMark email as unreadC
Mark an email as unread (clears the \Seen flag).
Inputs: uid (required), folder, server.
email_moveMove emailA
Move an email by UID to another folder.
Inputs: uid (required), destination (required), folder, server.
email_readRead emailBRead-only
Read a single email (headers + body) by UID.
Inputs: uid (required), folder, server.
email_replyReplyB
Reply to the sender of an email, threading preserved.
Inputs: uid (required), html, text, folder, +1 more.
email_reply_allReply allA
Reply to all recipients of an email (sender + To/Cc, excluding yourself), threading preserved.
Inputs: uid (required), html, text, folder, +1 more.
email_save_draftSave draftA
Compose a message and save it to the Drafts folder (does not send).
Inputs: subject (required), cc, to, html, +3 more.
email_searchSearch emailsARead-only
Search emails by from/to/subject/body/text, date range, and flags. Searches ALL folders unless a folder is given. Note: on the ox-api transport, body/text match only the subject and addresses of recent messages (not full message bodies); use the imap transport for true full-text search.
Inputs: to, body, from, seen, +8 more.
email_sendSend emailC
Send an email via SMTP.
Inputs: to (required), subject (required), cc, bcc, +5 more.
list_serversList serversARead-only
List configured accounts/servers and their mail/calDav/cardDav sections (hosts, users, auth types). Never returns secrets.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Tools are cleanly partitioned into email_*, calendar_*, and contact_* groups with distinct actions. A few email tools overlap slightly in effect (email_move vs email_archive vs email_mark_spam all relocate a message, and email_flag vs email_mark_read both set flags), but the descriptions clarify the boundaries well.
A consistent domain_verb_noun convention (email_create_folder, calendar_create_event, contact_create) dominates, with implied-noun variants (email_send, email_reply, email_delete) that stay readable. Minor deviation is the sub-resource prefix pattern in email_filter_list/email_filter_create/email_filter_update and email_list_folders, but overall predictable.
33 tools is on the heavy side, but the server genuinely spans three substantial domains (mail, calendar, contacts), and nearly every tool maps to a real operation. Slightly above the ideal range for a single MCP server but justified by scope.
Email coverage is strong (list/read/send/reply/draft/search/folders/flags/filters), and calendar covers the full event lifecycle including invitations. Minor gaps remain: no email_filter_delete, and contacts lack update/delete operations, but core workflows are covered.
Maintenance
Related MCP Connectors
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.1139 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for reading and sending emails via IMAP and SMTP, designed for Zimbra and any standard mail host.12 npm1ISC
- AlicenseNot gradedqualityDmaintenanceLocal MCP server for macOS Mail reads plus visible unsent compose, reply, and forward drafts, and constrained single-message moves.MIT
- AlicenseBqualityBmaintenanceA comprehensive MCP server that aggregates email, calendar, and contacts across Google, Microsoft, Zoho, and IMAP/SMTP services, designed for headless environments with OAuth device flow support.134MIT