Mac Mail MCP

Apple App MCP

Apple アプリのローカルデータをアシスタントに公開する MCP サーバーのワークスペースです。

パッケージ

パッケージ	ステータス	目的
mac-mail-mcp	ベータ	ディスクを優先して読み込み、本文を網羅的に FTS5 検索できる Mac Mail MCP サーバーです。
mac-calendar-mcp	アルファ	インデックス化したアーカイブを検索できる、読み取り専用の Mac Calendar MCP サーバーです。

クイックスタート

使用するパッケージをインストールします。

pipx install mac-mail-mcp
pipx install mac-calendar-mcp

高速検索のためにローカルインデックスを構築します。

mac-mail-mcp index --verbose
mac-calendar-mcp authorize
mac-calendar-mcp index

Calendar の認証時には、安定した macOS プライバシー ID を持つ小さなヘルパーアプリがインストールされます。一度だけ「カレンダーへのフルアクセス」のプロンプトを承認すると、ターミナル、MCP、およびスケジュールされた launchd による再構築で EventKit を一貫して使用できます。EventKit はその署名済みアプリの ID 内で実行されます。Calendar MCP は、匿名の osascript プロセスを介してヘルパーのスクリプトを実行しません。

任意の設定ファイルを生成します。

mac-mail-mcp init
mac-calendar-mcp init

インデックスの対象範囲は、ツールのデフォルト設定とは別に構成します。Mail の accounts や Calendar の calendars などの [index] 設定を使用してローカルに保存する対象を制御し、呼び出し元が対象範囲を指定しなかった場合に MCP ツールが使用する範囲は [defaults] 設定で制御します。

Codex CLI

一方または両方のサーバーを登録します。

codex mcp add mail -- mac-mail-mcp serve --watch
codex mcp add calendar -- mac-calendar-mcp serve --watch

登録を確認します。

codex mcp list
codex mcp get mail
codex mcp get calendar

Claude Code

プロジェクトのルートに .mcp.json を作成するか、編集します。

{
  "mcpServers": {
    "mail": {
      "command": "mac-mail-mcp",
      "args": ["serve", "--watch"]
    },
    "calendar": {
      "command": "mac-calendar-mcp",
      "args": ["serve", "--watch"]
    }
  }
}

ウォッチモードを有効にすると、MCP サーバーの実行中にインデックスが最新の状態に保たれます。Mail はファイルの変更を監視し、Calendar は起動時に同期した後、Calendar のローカル SQLite データベースファイルが変更されたときに更新します。

Claude Code のグローバル設定に同じ mcpServers オブジェクトを指定するには、~/.claude/mcp.json に記述します。

開発

このリポジトリは uv ワークスペースとして構成されています。各 MCP サーバーは packages/ の下にあり、それぞれ独自のパッケージメタデータ、ソース、テスト、README を備えています。

git clone https://github.com/wagamama/apple-app-mcp
cd apple-app-mcp
uv sync

# All packages
uv run ruff check packages/mac-mail-mcp/src packages/mac-calendar-mcp/src
uv run pytest

# Individual packages
uv run --package mac-mail-mcp pytest packages/mac-mail-mcp/tests
uv run --package mac-calendar-mcp pytest packages/mac-calendar-mcp/tests

配布物をビルドします。

uv build --package mac-mail-mcp
uv build --package mac-calendar-mcp

ドキュメント

• 共通のエージェント向け指示：AGENTS.md
• Mail のドメインに関するメモ：MAIL.md
• Calendar のドメインに関するメモ：CALENDAR.md
• MCP クライアントのセットアップガイド：docs/mcp-client-setup.md
• Calendar の実装計画：docs/superpowers/plans/2026-05-30-mac-calendar-mcp-implementation.md

ドキュメントは .github/workflows/docs.yml から GitHub Pages にデプロイされます。リポジトリでは一度だけ、Settings -> Pages -> Build and deployment -> Source: GitHub Actions で Pages を設定する必要があります。このワークフローはビルド済みの成果物をデプロイします。一部のリポジトリでは GitHub がデフォルトのワークフロートークンによる操作を拒否するため、Pages サイトの作成や有効化は試みません。

謝辞

このコードベースは imdinu/apple-mail-mcp を基にしています。このリポジトリが基盤としている Apple Mail MCP を作成した原作者およびコントリビューターの皆さまに、敬意と感謝を表します。

ライセンス

GPL-3.0-or-later