ox-mcp

ox-mcp

适用于 Open-Xchange 和基于标准的邮件平台 的 MCP 服务——在一个或多个账户中读取和搜索电子邮件、发送和回复邮件、管理服务器端筛选规则、日历事件和邀请、联系人，以及其他人的可用情况（忙闲）。

它使用标准的 IMAP + SMTP + ManageSieve + CalDAV + CardDAV，并支持 RFC 6638 忙闲查询，因此适用于任何 Open-Xchange 部署或符合标准的主机。使用你的 电子邮件 + 应用密码（与 DAVx5 使用的凭据相同）或 OAuth2/OIDC 进行身份验证。

与 Open-Xchange 无关联。

安装 / 运行

npx -y @rheopyrin/ox-mcp
# or with a custom config location:
npx -y @rheopyrin/ox-mcp --config /path/to/config.json

MCP 客户端配置（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": "[email protected]",
        "OX_MCP_MAIL_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "OX_MCP_CALDAV_SERVER": "dav.example.com",
        "OX_MCP_CALDAV_USER": "[email protected]",
        "OX_MCP_CALDAV_APP_PASSWORD": "yyyy-yyyy-yyyy-yyyy"
      }
    }
  }
}

首次运行时（未使用 --config），它会创建 ~/.ox-mcp/config.json（权限为 0600），其中列出所有功能标志——读取已启用，写入已禁用——主机配置留空，供你填写。

--config

--config <file>（或环境变量 OX_MCP_CONFIG；命令行标志优先）会加载指定的配置文件，而不是 ~/.ox-mcp/config.json。该文件必须存在——使用此覆盖选项时，不会自动创建任何文件。

工具

工具按协议域分组。只有启用后才会显示相应分组中的工具，且必须配置该分组的服务器主机（参见 验证）。

分组	读取（默认启用）	写入（默认禁用）
email_*（IMAP/SMTP/Sieve — mail 部分）	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 部分）	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 部分）	contact_list、contact_find	contact_create
元数据	list_servers（始终启用）	—

• 除 list_servers 外，每个工具都接受可选的 server 参数，用于指定目标账户。只有至少一个账户启用了相应标志时，该工具才会显示在工具列表中。
• 默认情况下，email_search 会搜索所有文件夹；传入 folder 可缩小范围。使用 ox-api 传输方式时，body/text 只会匹配近期邮件的主题和地址——如需真正的全文搜索，请使用 transport: "imap"。
• email_mark_spam / email_archive 会通过 IMAP 特殊用途属性查找垃圾邮件/归档文件夹，并在找不到时按名称回退。
• email_reply / email_reply_all 会保留邮件线程（In-Reply-To/References），并从全部回复的收件人中排除你自己的地址。
• 三个 RSVP 工具（calendar_accept_event / calendar_decline_event / calendar_tentative_event）共用一个功能标志：respondEvent（calDav 部分）。它们会重写邀请中的 PARTSTAT；服务器会通知组织者。
• contact_find 会在服务器端搜索联系人（CardDAV addressbook-query，RFC 6352），并在需要时自动回退到客户端筛选；fields 可将匹配范围缩小到 name/email/phone/org（默认使用 name + email）。可用于在调用 calendar_free_busy 前将姓名解析为电子邮件地址。contact_list 则会直接枚举联系人。

邮件筛选器

email_filter_create / email_filter_update 通过 ManageSieve（端口 4190，STARTTLS；需要基本身份验证／应用密码）管理服务器端 sieve 筛选器。规则支持针对 from/to/subject/任意标头的条件（AND 或 OR），以及 fileinto（移至文件夹）、discard、markRead、redirect 操作。

后端取决于 mail.transport：使用 ox-api（默认值）时，筛选器通过 OX mailfilter/v2 模块处理，并作用于帐户实际的网页邮箱规则（超出此模型所支持的测试条件／操作的规则会以只读方式列为 other）。使用 imap 时，ox-mcp 会通过 ManageSieve（端口 4190）管理自己的 sieve 脚本，并将其启用——该脚本处于启用状态时，其他脚本中的筛选器会变为非活动状态。

配置：按协议划分的区块

每个帐户最多由三个独立区块组成——mail、calDav、cardDav——每个区块都有自己的 server、auth（包括各自的登录 user）和 features。这与按协议分别设置应用密码的服务器（如 Open-Xchange）相匹配：Mail、CalDAV 和 CardDAV 密码可以各不相同。

{
  "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": "[email protected]", "appPassword": "mail-scoped-pw" },
        "features": { "search": true, "send": false /* per-tool flags */ }
      },
      "calDav": {
        "server": "dav.example.com",
        "auth": { "type": "basic", "user": "[email protected]", "appPassword": "caldav-scoped-pw" },
        "features": { "respondEvent": false /* … */ }
      },
      "cardDav": {
        "server": "dav.example.com",
        "auth": { "type": "basic", "user": "[email protected]", "appPassword": "carddav-scoped-pw" }
      }
    }
  }
}

• 未配置的区块，其工具会被禁用。 仅配置 calDav 完全有效。
• mail.transport 是可选项，默认值为 "ox-api"——即 Open-Xchange HTTP API（网页邮箱后端，https://<server>/appsuite/api）。OX 部署会在此中间件验证应用密码，因此即使原始 IMAP 拒绝应用密码，也能正常使用；server 是网页邮箱主机。筛选器工具使用 OX mailfilter/v2 模块——它们会列出并编辑帐户的实际网页邮箱规则。注意：搜索会匹配主题／地址（而非完整正文）。
• 对通用（非 OX）邮件主机使用直接 IMAP/SMTP 时，设置 transport: "imap"——此时 server 为邮件主机，也可选择分别设置 imap/smtp 端点。
• 区块上的 enabled: false 是针对该区块所有工具的配置总开关。
• 没有全局 features 区块——标志仅位于各区块内（环境变量仍为全局变量）。

功能标志

解析优先级——环境变量始终优先于配置，采用第一个已定义的值：

1. 每个帐户的环境变量，工具级——OX_MCP_<ID>_ENABLE_EMAIL_SEND
2. 每个帐户的环境变量，分组级——OX_MCP_<ID>_ENABLE_MAIL
3. 全局环境变量，工具级——OX_MCP_ENABLE_EMAIL_SEND
4. 全局环境变量，分组级——OX_MCP_ENABLE_MAIL / _CALDAV / _CARDDAV
5. 区块配置，工具级——servers.<id>.mail.features.send
6. 区块配置，总开关——servers.<id>.mail.enabled
7. 默认值——读取操作为 true，写入操作为 false

# 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

布尔值接受 true/1/yes/on 和 false/0/no/off。

连接与凭据（环境变量）

每个区块字段都可通过环境变量设置：OX_MCP_[ID_]<SECTION>_<FIELD>，其中 SECTION ∈ MAIL | CALDAV | CARDDAV。默认帐户使用不带索引的形式。

环境变量	含义
OX_MCP_MAIL_SERVER / OX_MCP_CALDAV_SERVER / OX_MCP_CARDDAV_SERVER	区块主机
OX_MCP_MAIL_USER / OX_MCP_CALDAV_USER / OX_MCP_CARDDAV_USER	区块登录用户
OX_MCP_MAIL_APP_PASSWORD / OX_MCP_CALDAV_APP_PASSWORD / …	区块应用密码（基本身份验证）
OX_MCP_MAIL_IMAP_HOST / _IMAP_PORT / _SMTP_HOST / _SMTP_PORT	邮件传输覆盖设置（Gmail 式的分离主机）
OX_MCP_MAIL_IMAP_SECURE / _SMTP_SECURE	在非标准端口上强制使用 TLS（true）或 STARTTLS（false）
OX_MCP_MAIL_AUTH_TYPE、_CLIENT_ID、_REFRESH_TOKEN、…	按区块设置的 OAuth/OIDC 字段
OX_MCP_TIMEOUT_SECONDS	所有 HTTP/IMAP/SMTP 操作的请求超时时间（默认值为 300）

默认端口：IMAP 993、SMTP 465、DAV 443、ManageSieve 4190。除非显式设置 secure，否则 TLS 模式根据端口确定（993/465 使用隐式 TLS；143/587 使用 STARTTLS）。

验证

启动时会严格验证配置：每个已配置且启用了工具的区段都必须有服务器（邮件需分别配置 IMAP/SMTP 主机）和登录用户，否则服务器会退出并报错，指出确切字段。没有任何区段的账户也会报错。未配置的区段会直接禁用，不会报错。

身份验证类型

默认使用 basic（应用密码）。每个区段还支持其他与 Open-Xchange 对齐的机制，通过 auth.type / OX_MCP_[ID_]<SECTION>_AUTH_TYPE 配置：

类型	额外字段（环境变量：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 或 PASSWORD、SCOPE

令牌会自动缓存和刷新。注意：邮件筛选器（ManageSieve）需要使用 basic 身份验证。

多个账户

OX_MCP_ACCOUNTS=work,personal
OX_MCP_WORK_MAIL_SERVER=mail.work.com
[email protected]
OX_MCP_WORK_MAIL_APP_PASSWORD=...
OX_MCP_PERSONAL_CALDAV_SERVER=dav.personal.com
[email protected]
OX_MCP_PERSONAL_CALDAV_APP_PASSWORD=...
OX_MCP_DEFAULT_SERVER=work

也可以在 ~/.ox-mcp/config.json 的 servers 下定义账户（以 ID 为键）。list_servers 会显示已配置的内容（绝不显示机密）；环境变量会逐字段覆盖配置。不同账户可以使用不同的功能标志（例如，仅在 work 上启用发送功能）。

空闲/忙碌注意事项

calendar_free_busy 仅通过 CalDAV 调度发件箱返回可用时间段（忙碌/空闲），无需共享日历。它不会透露事件详情，并且要求服务器公布 schedule-outbox-URL。若要读取同事的完整日历，对方必须将日历共享给你的账户；共享日历随后会显示在 calendar_list / calendar_list_events 中。

Docker

docker build -t ox-mcp .
docker run -i --rm \
  -e OX_MCP_MAIL_SERVER=mail.example.com \
  -e [email protected] \
  -e OX_MCP_MAIL_APP_PASSWORD=xxxx \
  ox-mcp

开发

npm install
npm run dev          # run from source
npm test             # vitest
npm run test:coverage
npm run build        # bundle to dist/ (tsup)

许可证

MIT