rubit-mcp-mail

rubit-mcp-mail

メールを読むための読み取り専用 MCP サーバーです。プロバイダーに依存せず、IMAP を使用するため、Outlook.com、Gmail、Fastmail、iCloud、またはセルフホストのサーバーで動作します。プロバイダーの変更は設定を1行変えるだけで、コードを変更する必要はありません。

設計上、読み取り専用です。 フォルダーは SELECT ではなく EXAMINE で開き、本文は BODY.PEEK で取得するため、メッセージを読んでも既読になりません。送信、移動、削除、フラグ設定を行うコードパスはなく、それらが追加されていないことをテストで確認しています。

📖 完全なドキュメント：https://bgalmes.github.io/rubit-mcp-mail/

クイックインストール

お使いのシステム用のインストーラーを 最新リリースからダウンロードして実行してください。

システム	ファイル
Windows	rubit-mcp-mail-setup-windows.exe
Linux	rubit-mcp-mail-setup-linux — 先に chmod +x を実行してください

事前にインストールしておくものはありません。Python とすべての依存関係は、1つのファイルに含まれています。ウィンドウでプロバイダーとメールアドレスを指定するとサインインし、Claude Desktop と Claude Code が見つかった場合はメールサーバーを登録します。あとは Claude Desktop を再起動すれば、メールを利用できます。また、後から変更したい項目を設定できる rubit-mcp-mail Settings ショートカットも作成されます。ターミナルは一切不要です。

macOS 用のインストーラーはありません。Mac では、以下の手順でソースからインストールしてください。

ウイルス対策ソフトの警告について。 Windows Defender や Avast がこの .exe を警告する場合があります。これは、署名されていない PyInstaller 製アプリケーションでよく見られる既知の誤検知であり、このプロジェクトのコードが原因ではありません。対処方法については、 インストールガイドをご覧ください。公開済みの SHA-256 はすべて 変更履歴に記載されています。

ツール

ツール	機能
list_accounts	設定済みアカウントと、それぞれの認証状態を表示します
list_folders	正規化された役割と未読件数を含むフォルダーを表示します
list_messages	フォルダー内のメッセージを新しい順にページ分割して表示します
search_messages	テキスト、送信者、件名、日付範囲、未読状態でサーバー側検索を行います
read_message	完全なヘッダー、本文テキスト、添付ファイルのメタデータを表示します
get_attachment	添付ファイルを1つダウンロードディレクトリに保存します

フォルダーは 役割（inbox、sent、drafts、junk、trash、archive）で指定するため、Outlook では Junk Email、Gmail では [Gmail]/Spam と呼ばれる、といった違いを把握する必要はありません。実際のフォルダー名も使用できます。

引数と戻り値の形式の詳細： ツールリファレンス。

pip でインストール

すでに Python 3.11 以降をお使いで、インストーラーを実行せずにインストールしたい場合：

pip install rubit-mcp-mail
rubit-mcp-mail install      # the same setup wizard, from the terminal

ソースからインストール

cd /path/to/rubit-mcp-mail
conda create -p ./.venv python=3.12 pip -y     # this machine has no python3-venv
./.venv/bin/python -m pip install -e .

続いてアカウントを設定し、rubit-mcp-mail auth <account> と rubit-mcp-mail doctor を実行してください。Windows 向けの手順と詳しいガイドは ソースからインストールをご覧ください。

メールボックスの設定

Microsoft は Outlook.com の基本認証を廃止したため、Outlook を使うには無料の Azure アプリ登録が必要です。一度だけ行う 7 つの手順を、 Outlook の設定にまとめています。 それ以外のサービスでは、アプリパスワードを用意するだけです。

[accounts.personal]
provider = "generic"
email    = "[email protected]"
host     = "imap.fastmail.com"

既知のホスト：Gmail は imap.gmail.com、Fastmail は imap.fastmail.com、 iCloud は imap.mail.me.com、Yahoo は imap.mail.yahoo.com です。Gmail と iCloud では、 ログインパスワードではなくアプリ専用パスワードが必要です。

独自の Azure アプリを登録できませんか？

Microsoft アカウントで本当にアプリを登録できない場合は、他のオープンソースのメールツールが この目的ですでに共有している公開クライアント ID（Thunderbird のもの）を使えます。 client_id に 9e5f94bc-e8a4-4e73-b8be-63364c29d753 を貼り付けてください。 同意画面には「Thunderbird」と表示されます。また、この ID は当方の管理外のため、Microsoft が 変更する可能性があります。詳細と注意事項： 独自のアプリを登録できませんか？。

権限

アカウント単位のツールは、config.toml の disabled_tools で無効にするか、設定ウィンドウの 「Permissions」タブでチェックを外すことで、特定のアカウントで禁止できます。ブロックされた呼び出しは 暗黙に失敗するのではなく、モデルに通常の Error: ... 文字列を返します。詳しくは 権限をご覧ください。

Claude への登録

claude mcp add rubit-mail --scope user -- "$(pwd)/.venv/bin/rubit-mcp-mail" serve

Claude Desktop では代わりに JSON エントリが必要です。また、Linux ではキーリングにアクセスできるよう、 セッション環境を明示的に渡す必要があります。 Claude への登録には両方の方法が記載されており、 ログについてはトラブルシューティングをご覧ください。

エージェントスキル

skills/rubit-mail/SKILL.mdでは、エージェントがメールツールを使うタイミングと ツールの連携方法を説明し、サーバーが読み取り専用であること、メールの内容は信頼できないことも伝えています。 Claude Code の場合は、ユーザーまたはプロジェクトの .claude/ スキルディレクトリにコピーしてください。

mkdir -p ~/.claude/skills && cp -r skills/rubit-mail ~/.claude/skills/

SKILL.md ファイルを読み込む他のエージェントでも同様に利用できます。詳しくは エージェントスキルをご覧ください。

開発

ruff check .
ruff format --check .
pyright
pytest -q

これらは CI で実行されるチェックと同じです。コミットメッセージは Conventional Commits に準拠し、自動バージョン管理に使用されます。 CONTRIBUTING.mdと AGENTS.mdをご覧ください。 インストーラーのビルドとプロバイダーの追加については、 コントリビューションで説明しています。

ウェブサイト

website/ にはドキュメントサイト（Nuxt）があり、 .github/workflows/deploy-website.yml によって GitHub Pages にデプロイされます。 ドキュメントの正式な参照元はこのサイトです。この README は意図的に簡潔な内容にしています。

重要

ウェブサイトに関するコミットでは、feat: または fix: を使用しないでください。 python-semantic-release はスコープではなくコミットの type を解析するため、 feat(site): … とすると Python パッケージのバージョンが上がり、インストーラーのリリースが行われます。 docs(site):、chore(site):、または ci(site): を使用してください。

構成

src/rubit_mcp_mail/
  server.py        MCP tool definitions
  __main__.py      CLI: serve | install | auth | doctor | gui
  installer.py     setup wizard: writes config, signs in, registers with Claude
  installer_gui.py the setup window (tkinter), falling back to the terminal
  shortcuts.py     Start Menu / Desktop / .desktop entries for the GUI
  claude_registration.py  claude_desktop_config.json / `claude mcp add`
  session.py       wires config + auth + backend; attachment path safety
  config.py        TOML config -> Account models
  diagnostics.py   the doctor checks, as data (shared by the CLI and the GUI)
  permissions.py   registry of per-account-toggleable tool names
  config_editor.py every write to config.toml: comment-preserving, validated
  config_gui.py    the settings window (tkinter): accounts, permissions, doctor
  providers.py     provider profile registry
  secrets.py       keyring with 0600-file fallback
  models.py        pydantic models + message handles
  mime.py          BODYSTRUCTURE walking, decoding, HTML->text
  backends/
    base.py        MailBackend protocol
    imap.py        the IMAP implementation
  auth/
    password.py         app passwords
    oauth_microsoft.py  MSAL device-code flow
skills/rubit-mail/SKILL.md  agent skill: when and how to use the tools
website/           the documentation site (Nuxt); see "The website" above

リリース

main へのマージごとに、pyproject.toml と CHANGELOG.md の差分のみを含むリリース PR が準備されます。 メンテナーが手動でマージすると、プレリリースが公開され、インストーラーがビルドされます。 promote-release.yml は手動で実行し、-rc.N サフィックスを取り除きます。 人によるマージは不可欠です。GitHub は GITHUB_TOKEN による操作に対してイベントを発生させないためです。 全体の手順については、 CONTRIBUTING.mdと リリースの仕組みをご覧ください。

注意事項と制限

IMAP 検索は部分一致方式で、本文は 20,000 文字で切り詰められ、テキスト部分のみがダウンロードされます。また、Microsoft はサードパーティーによるメールへのアクセスを積極的に制限しています。詳細については、 注意事項と制限をご覧ください。