Skip to main content
Glama

ox-mcp

npm npm downloads license: MIT node

ox-mcp MCP server

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.json

MCP 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)

email_* (IMAP/SMTP/Sieve — mail section)

email_list_folders, email_list, email_read, email_search, email_filter_list

email_send, email_save_draft, email_reply, email_reply_all, email_delete, email_move, email_flag, email_mark_read, email_mark_unread, email_mark_spam, email_archive, email_create_folder, email_delete_folder, email_filter_create, email_filter_update

calendar_* (CalDAV — calDav section)

calendar_list, calendar_list_events, calendar_free_busy

calendar_create_event, calendar_update_event, calendar_delete_event, calendar_accept_event, calendar_decline_event, calendar_tentative_event

contact_* (CardDAV — cardDav section)

contact_list, contact_find

contact_create

meta

list_servers (always on)

—

  • Every tool (except list_servers) accepts an optional server argument to target a specific account. A tool is hidden from the tool list unless its flag is enabled for at least one account.

  • email_search searches all folders by default; pass folder to narrow it. On the ox-api transport, body/text match only the subject and addresses of recent messages — use transport: "imap" for true full-text search.

  • email_mark_spam / email_archive find the Junk/Archive folder via IMAP special-use attributes, with name-based fallbacks.

  • email_reply / email_reply_all preserve 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 your PARTSTAT on the invitation; the server notifies the organizer.

  • contact_find searches contacts server-side (CardDAV addressbook-query, RFC 6352) with automatic fallback to client-side filtering; fields narrows the match to name/email/phone/org (default name + email). Handy for resolving a name to an email before calendar_free_busy. contact_list is 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 OX mailfilter/v2 module and operate on the account's real webmail rules (rules with tests/actions beyond this model are listed read-only as other). 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.transport is 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; server is the webmail host. Filter tools use the OX mailfilter/v2 module — 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 — then server is the mail host, with optional split imap/smtp endpoints.

  • enabled: false on 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:

  1. per-account env, tool — OX_MCP_<ID>_ENABLE_EMAIL_SEND

  2. per-account env, group — OX_MCP_<ID>_ENABLE_MAIL

  3. global env, tool — OX_MCP_ENABLE_EMAIL_SEND

  4. global env, group — OX_MCP_ENABLE_MAIL / _CALDAV / _CARDDAV

  5. section config, tool — servers.<id>.mail.features.send

  6. section config, master — servers.<id>.mail.enabled

  7. default — true for reads, false for 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=true

Booleans 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

OX_MCP_MAIL_SERVER / OX_MCP_CALDAV_SERVER / OX_MCP_CARDDAV_SERVER

section host

OX_MCP_MAIL_USER / OX_MCP_CALDAV_USER / OX_MCP_CARDDAV_USER

section login user

OX_MCP_MAIL_APP_PASSWORD / OX_MCP_CALDAV_APP_PASSWORD / …

section app password (basic auth)

OX_MCP_MAIL_IMAP_HOST / _IMAP_PORT / _SMTP_HOST / _SMTP_PORT

mail transport overrides (Gmail-style split hosts)

OX_MCP_MAIL_IMAP_SECURE / _SMTP_SECURE

force TLS (true) or STARTTLS (false) on a non-standard port

OX_MCP_MAIL_AUTH_TYPE, _CLIENT_ID, _REFRESH_TOKEN, …

per-section OAuth/OIDC fields

OX_MCP_TIMEOUT_SECONDS

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: OX_MCP_[ID_]<SECTION>_…)

basic

APP_PASSWORD

xoauth2

ACCESS_TOKEN

oauth2-refresh

CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, TOKEN_URL, SCOPE

oauth2-password

CLIENT_ID, CLIENT_SECRET, PASSWORD, TOKEN_URL, SCOPE

oidc

ISSUER, CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN or PASSWORD, SCOPE

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=work

Or 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-mcp

Development

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 tools
calendar_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 eventB
Destructive

Delete a calendar event by its object URL.

Inputs: objectUrl (required), etag, server.

calendar_free_busyGet free/busyA
Read-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 calendarsA
Read-only

List CalDAV calendars (own and any shared with the account).

Inputs: server.

calendar_list_eventsList calendar eventsB
Read-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 contactsA
Read-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 contactsA
Read-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 emailA
Destructive

Delete an email by UID (moves to Trash or expunges per server policy).

Inputs: uid (required), folder, server.

email_delete_folderDelete mail folderA
Destructive

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 filtersA
Read-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 emailsB
Read-only

List the most recent emails in a folder (newest first).

Inputs: limit, folder, server.

email_list_foldersList mail foldersC
Read-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 emailB
Read-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_sendSend emailC

Send an email via SMTP.

Inputs: to (required), subject (required), cc, bcc, +5 more.

list_serversList serversA
Read-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

    B3.4/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.
      11
      39 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for reading and sending emails via IMAP and SMTP, designed for Zimbra and any standard mail host.
      12 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local MCP server for macOS Mail reads plus visible unsent compose, reply, and forward drafts, and constrained single-message moves.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A 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.
      13
      4
      MIT