addy.io

addy-mcp

Claude（およびその他の MCP クライアント）から addy.io アカウントを管理できる MCP サーバーです。エイリアス、受信者、ユーザー名、カスタムドメイン、ラベル、ルール、ブロックリスト、配信失敗を管理できます。addy.io API の全機能をカバーしています。

非公式です。 このプロジェクトは addy.io とは提携しておらず、承認も受けていません。

ご自身の API キーを使って、ご自身のコンピューター上で実行します。ホストされているものはなく、キーが送信されるのは addy.io だけです。

1. API キーを作成する

addy.io で Settings → API Keys（https://app.addy.io/settings/api）を開き、Create New API Key をクリックします。「Claude」のような名前と有効期限を設定することをおすすめします。

2. インストール

Claude Desktop（最も簡単）

1. Releases ページから最新の addy-mcp-<version>.mcpb をダウンロードします。
2. ダブルクリックするか、Claude Desktop の Settings → Extensions にドラッグして、Install をクリックします。
3. 求められたら API キーを貼り付けます。Claude Desktop が暗号化して保存します。

Claude Desktop（手動設定）

uv が必要です。Settings → Developer → Edit Config を開き、次を追加します。

{
  "mcpServers": {
    "addy": {
      "command": "uvx",
      "args": ["addy-mcp@latest"],
      "env": {
        "ADDY_API_KEY": "paste-your-api-key-here"
      }
    }
  }
}

Claude Desktop を完全に終了してから、再度開きます。uvx が見つからない場合は、"uvx" を which uvx（macOS/Linux）または where uvx（Windows）で確認したフルパスに置き換えてください。デスクトップアプリからシェルの PATH が常に参照できるとは限りません。

Claude Code

claude mcp add addy --scope user --env ADDY_API_KEY=paste-your-api-key-here -- uvx addy-mcp@latest

これにより、Claude Code（CLI とデスクトップアプリの Code タブ）でサーバーを利用できるようになります。Claude Desktop のチャットでは別の設定を使うため、上記の手順で設定してください。

その他の MCP クライアント

環境変数に ADDY_API_KEY を設定し、stdio サーバーとして uvx addy-mcp@latest を実行します。

@latest を付けると、サーバーの起動時に uvx が PyPI で新しいリリースを確認します。省略すると、uvx は最初にダウンロードしたバージョンを使い続けます。特定のバージョンを使う場合は、たとえば addy-mcp==0.1.1 を指定します。

設定

環境変数	必須	説明
ADDY_API_KEY	はい*	addy.io の API キーです。
ADDY_API_KEY_FILE	いいえ	ADDY_API_KEY の代わりに使用する、キーを含むファイルのパスです。両方が設定されている場合はこちらが優先されます。*どちらか一方が必須です。
ADDY_READ_ONLY	いいえ	true に設定すると、アカウントを変更できるすべてのツールが非表示になります。その場合、Claude は情報の参照のみ行えます。
ADDY_BASE_URL	いいえ	セルフホスト可能な addy.io インスタンス用です。例：https://addy.example.com。デフォルトは https://app.addy.io です。

キーを安全に保管する

上記の設定では、キーはMCPクライアントの設定ファイルにプレーンテキストで保存されます。これはローカルMCPサーバーで一般的な方法ですが、より安全に保管する方法があります。

• Claude Desktop拡張機能： .mcpb でインストールすると、キーは暗号化して保存されます。ほかに必要な作業はありません。

• macOSキーチェーン（Claude Codeおよびその他のクライアント）： キーをキーチェーンに保存し、サーバーの起動時にのみ取得すれば、設定ファイルに書き込まれることはありません。キーを追加します（入力を求められるため、シェルの履歴には残りません）。

  security add-generic-password -a "$USER" -s addy-mcp -w
  

  次に、--env の代わりに小さなラッパーを使ってサーバーを追加します。

  claude mcp add addy --scope user -- /bin/sh -c 'ADDY_API_KEY="$(security find-generic-password -a "$USER" -s addy-mcp -w)" || exit 1; export ADDY_API_KEY; exec uvx addy-mcp@latest'
  

  uvx が見つからずサーバーを起動できない場合は、uvx を which uvx で確認できるフルパスに置き換えてください。

  Linuxでは、同じ方法を secret-tool store --label=addy-mcp service addy-mcp と secret-tool lookup service addy-mcp で利用できます。1Passwordでは、security コマンドの代わりに op read "op://<vault>/<item>/credential" を使います。

• キーファイル： 自分だけが読み取れるファイル（chmod 600）、またはDockerやKubernetesのシークレットマウントに ADDY_API_KEY_FILE を設定します。

• VS Code： VS Codeでキーの入力を求め、シークレットストレージに保存します。

  {
    "inputs": [
      { "type": "promptString", "id": "addy-api-key", "description": "addy.io API key", "password": true }
    ],
    "servers": {
      "addy": {
        "type": "stdio",
        "command": "uvx",
        "args": ["addy-mcp@latest"],
        "env": { "ADDY_API_KEY": "${input:addy-api-key}" }
      }
    }
  }
  

どの方法を選ぶ場合も、アプリやデバイスごとに別のaddy.ioキーを使い、ほかに影響を与えずにキーを無効化できるようにしてください。また、有効期限を設定してください。

更新

• addy-mcp@latest でインストールした場合（上記のコマンド）：Claude（またはMCPクライアント）を再起動すると、最新リリースが自動的に適用されます。
• uvx addy-mcp でインストールした場合： uvxは最初にダウンロードしたバージョンを使い続けます。設定で addy-mcp を addy-mcp@latest に変更してから、Claudeを再起動してください。
• Claude Desktop拡張機能（.mcpb）： リリースページから新しい .mcpb をダウンロードし、同じ方法でインストールしてください。APIキーと設定は保持されるため、再入力する必要はありません。

最新バージョンを確認するには、uvx addy-mcp@latest --version を実行します（0.1.1以降で利用可能）。新しいリリースのお知らせを受け取るには、GitHubでリポジトリをウォッチしてください（Watch → Custom → Releases）。変更内容は変更履歴に記載されています。

できること

• 「Netflixアカウント用の新しいエイリアスを作って。」
• 「最も多くのメールをブロックしたエイリアスはどれ？上位5つを無効化して。」
• 「ショッピングサイト用に作成したエイリアスをすべて見つけて、『Shopping』というラベルを付けて。」
• 「marketing.example.com からのメールをすべてブロックして。」
• 「shop@エイリアス宛てのニュースレター（List-Unsubscribeヘッダー）をブロックするルールを作成して。」
• 「先週、銀行のエイリアス宛てのメールが届かなかったのはなぜ？」

ツール

領域	ツール
アカウント	get_account_details、get_api_token_details、get_account_notifications、get_domain_options、get_app_version
エイリアス	list_aliases、get_alias、create_alias、update_alias、delete_alias、restore_alias、forget_alias、set_alias_option（active / pinned / attached-recipients-only）、set_alias_recipients、set_alias_labels
一括エイリアス	bulk_alias_action（get / activate / deactivate / pin / unpin / delete / restore / forget）、bulk_set_alias_recipients、bulk_set_alias_labels
宛先	list_recipients、get_recipient、create_recipient、update_recipient、delete_recipient、resend_recipient_verification、add_recipient_public_key、remove_recipient_public_key、set_recipient_option（active / can reply-send / encryption / inline encryption / protected headers / strip PGP keys / strip PGP signatures）
ユーザー名	list_usernames、get_username、create_username、update_username、delete_username、set_username_default_recipient、set_username_option（active / catch-all / can login）
ドメイン	list_domains、get_domain、create_domain、update_domain、delete_domain、set_domain_default_recipient、check_domain_sending_records、set_domain_option（active / catch-all / shared with family）
ラベル	list_labels、get_label、create_label、update_label、delete_label
ルール	list_rules、get_rule、create_rule、update_rule、delete_rule、reorder_rules、set_rule_active
ブロックリスト	list_blocklist、add_to_blocklist、remove_from_blocklist
配信失敗	list_failed_deliveries、get_failed_delivery、download_failed_delivery、resend_failed_delivery、delete_failed_deliveries

各ツールには読み取り専用、書き込み、破壊的操作のいずれかのラベルが付いているため（MCP ツールのアノテーション）、Claude などのクライアントはリスクのある操作を実行する前に確認できます。エイリアスの削除は restore_alias で取り消せます。エイリアスを完全に消去すると、元に戻せません。

プライバシーとセキュリティ

• サーバーはローカルで実行され、addy.io（または ADDY_BASE_URL）とのみ通信します。テレメトリーはありません。
• API キーを使うと、addy.io アカウントに完全にアクセスできます。単独で失効できるよう専用のキーを使用し、Claude に情報の検索だけをさせたい場合は ADDY_READ_ONLY を有効にしてください。
• ツールが返す情報（エイリアスのアドレス、説明、配信失敗メール）は AI クライアントに渡され、そのクライアントのプライバシーポリシーが適用されます。

開発

git clone https://github.com/Former-Stranger/addy-mcp
cd addy-mcp
uv run --no-editable python -m pytest      # unit tests (mocked HTTP, never touch a real account)
uv run ruff check && uv run ruff format --check

scripts/live_test.py は実際のアカウントに対してサーバーをテストします。使い捨てのエイリアスとラベルを作成、更新、削除、復元し、最後に完全に消去します。ADDY_API_KEY=... uv run --no-editable python scripts/live_test.py --yes を実行してください。

--no-editable：一部の macOS 環境では、.venv 内のファイルに「非表示」フラグが付くことがあり、Python 3.13 以降では非表示の .pth ファイルが無視されるため、編集可能インストールが機能しません。通常のインストールならこの問題を回避できます。

リリース

1. pyproject.toml の version を更新し、uv run python scripts/sync_metadata.py を実行してから、CHANGELOG.md を更新します。
2. コミットし、タグを付けてプッシュします：git tag v0.2.0 && git push origin v0.2.0。
3. GitHub から求められたら、pypi のデプロイを承認します（メンテナーが承認するまでリリースは一時停止します）。

リリースワークフローでは PyPI に公開し、.mcpb バンドルを GitHub リリースに添付して、MCP Registry の掲載情報を更新します。

毎週実行されるワークフローでは、addy.io API ドキュメント と scripts/addy_api_snapshot.txt を比較し、API に変更があった場合は issue を作成します。ツールを更新した後、python3 scripts/check_api_docs.py --update を実行してスナップショットを更新してください。Dependabot は依存関係と GitHub Actions の更新について、毎週プルリクエストを作成します。

ライセンス

MIT