ox-mcp

ox-mcp

Open-Xchange および標準準拠のメールプラットフォーム向けの MCP サーバーです。1 つまたは複数のアカウントで、メールの閲覧と検索、送信と返信、サーバー側フィルターの管理、カレンダーの予定と招待、連絡先、他のユーザーの空き時間（free/busy）などを利用できます。

標準の 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
meta	list_servers（常に有効）	—

• list_servers を除くすべてのツールは、特定のアカウントを対象にするための server 引数を省略可能です。少なくとも 1 つのアカウントで機能フラグが有効になっていないツールは、ツール一覧に表示されません。
• email_search はデフォルトですべてのフォルダーを検索します。検索範囲を絞るには folder を指定してください。ox-api トランスポートでは、body／text は最近のメッセージの件名とアドレスのみを対象にします。全文検索を行うには transport: "imap" を使用してください。
• email_mark_spam／email_archive は、IMAP の special-use 属性を使って迷惑メール／アーカイブフォルダーを検索し、見つからない場合は名前をもとに検索します。
• email_reply／email_reply_all はスレッドを維持し（In-Reply-To／References）、全員に返信する際は自分のアドレスを受信者から除外します。
• 3 つの RSVP ツール（calendar_accept_event／calendar_decline_event／calendar_tentative_event）は、1 つの機能フラグ（calDav セクションの respondEvent）を共有します。招待の 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 スクリプトを管理し、有効化します。有効化中は、他のスクリプトのフィルターは無効になります。

設定：プロトコルごとのセクション

各アカウントは、最大 3 つの独立したセクション（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 ホスト）とログインユーザーの両方が必要です。満たされていない場合、サーバーは該当するフィールド名を示すエラーを出して終了します。セクションが1つもないアカウントもエラーになります。存在しないセクションは単に無効として扱われ、エラーにはなりません。

認証タイプ

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 のみで有効にする）。

Free/busy に関する注意点

calendar_free_busy は、CalDAV のスケジューリング用 outbox を通じて、空き時間帯（予定あり／空き）のみを返します。カレンダーの共有は必要ありません。イベントの詳細は表示されません。また、サーバーが 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