addy.io

addy-mcp

一个 MCP 服务，可让 Claude（以及其他 MCP 客户端）管理你的 addy.io 账户：别名、收件人、用户名、自定义域名、标签、规则、屏蔽列表和投递失败记录。它涵盖完整的 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）返回的完整路径。桌面应用不一定能访问 shell 的 PATH。

Claude Code

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

这样就能在 Claude Code（命令行和桌面应用的 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 和其他客户端）：**将密钥保存在钥匙串中，仅在服务启动时获取，这样就不会将密钥写入配置文件。添加密钥（系统会提示你输入，因此密钥不会出现在 shell 历史记录中）：

  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 时，请用 op read "op://<vault>/<item>/credential" 替代 security 命令。

• **密钥文件：**将 ADDY_API_KEY_FILE 设置为只有你能读取的文件（chmod 600），或设置为 Docker 或 Kubernetes 密钥挂载路径。

• **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）：**从 Releases 页面下载新版 .mcpb，并按相同方式安装。你的 API 密钥和设置都会保留，因此无需再次输入。

如需查看最新版本，请运行 uvx addy-mcp@latest --version（从 0.1.1 版本开始提供）。如需接收新版本通知，请在 GitHub 上关注仓库（Watch → Custom → Releases）。变更记录列在更新日志中。

你可以这样提问

• “为我的 Netflix 账户创建一个新别名。”
• “我的哪些别名拦截的邮件最多？停用排名前 5 的别名。”
• “找出我为购物网站创建的所有别名，并将它们标记为‘购物’。”
• “拦截来自 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