simplelogin-mcp

simplelogin-mcp

一款面向现有 SimpleLogin 用户的独立、可自托管 Model Context Protocol 服务。它允许兼容的 MCP 客户端创建和管理别名、查看别名活动元数据、使用反向别名、管理路由，并通过你运行的服务查看账户设置。

独立项目： simplelogin-mcp 是一个独立的开源项目。它不是 SimpleLogin 或 Proton AG 的官方产品、服务或 MCP 实现，也未与 SimpleLogin 或 Proton AG 建立关联、获得认可或赞助。

概览

• 本地 stdio 是单个本地 MCP 客户端最简单的入门方式。客户端会启动服务，而不会打开网络监听器。
• 直接使用 Node.js — Streamable HTTP 会运行一个持久服务，供支持 HTTP 的 MCP 客户端使用，默认监听环回地址。
• Docker Compose — Streamable HTTP 会在你偏好使用 Docker 管理服务时运行已发布的容器，默认仅向环回地址发布主机端口。
• SL_API_KEY 可完全控制你的 SimpleLogin 账户。请勿将其放入提示词、日志、Shell 历史记录或版本控制中。
• 工具名称、输入、安全注释、限制和输出说明均来自服务所用的同一份目录和架构。

文档

网站是用户文档的权威来源：

• 开始使用
• 创建 SimpleLogin API 密钥
• 设置 MCP 客户端
• 浏览工具目录
• 查看 API 覆盖范围和非目标
• 了解安全与数据
• 运行已部署的服务
• 排查安装问题
• 查看已发布的容器包

面向仓库维护者的文档仍与代码一同保留：

• 实时冒烟测试操作手册
• 注册表就绪情况
• 发布流程
• 贡献指南
• 支持政策
• 漏洞报告

工具

工具目录涵盖别名、联系人和反向别名、邮箱、 自定义域名、通知和账户设置。对于结果可能较大的读取操作，均设置了上限；永久删除则需要明确确认。

请使用可搜索的网站工具目录查看当前公开功能，或阅读源代码旁生成的 TOOL_CATALOG.md。端点级支持范围和明确的非目标请参阅 API 覆盖范围。

常见工作流

工作流指南提供完整且便于审核的操作步骤。以下概要保留了最常见的入口。

创建和整理别名

使用 alias_list 查找现有别名，然后再通过 alias_create_random 创建别名。要创建自定义地址，请先查看 alias_options_get，再调用 alias_create_custom。使用 alias_update 整理备注、名称和置顶状态，并使用 alias_set_enabled 明确启用或停用别名。

如需了解我个人整理 SimpleLogin 别名的方式，请阅读我如何整理电子邮件。

审核近期别名活动

使用 alias_list 或 alias_get 查找别名，然后通过 alias_activity_list 检查分页范围受限的活动元数据。结果会描述转发、回复、拦截和退信；服务端不会读取电子邮件正文。

创建用于发送的反向别名

使用 contact_list 检查某个别名的现有收件人，然后在需要时使用 contact_create 创建或复用反向别名。从拥有该别名的真实邮箱向返回的反向别名地址发送实际邮件。MCP 服务会创建路由地址；它不会撰写或发送电子邮件。

管理邮箱

在创建、更新或删除邮箱之前，先使用 mailbox_list。新地址需要在 SimpleLogin 中验证；永久删除则必须同时设置 confirm: true，并明确决定如何转移或删除所拥有的别名。

维护自定义域名

服务端可以检查并更新现有自定义域名的受支持设置。域名的创建、删除、DNS 和 MX 验证仍需在 SimpleLogin 的官方界面中进行。

查看账户状态

使用 account_get_stats 获取账户汇总计数，使用 notification_list 查看分页范围受限的账户通知，并在通过 settings_update 进行受支持的更改之前使用 settings_get。

安装和运行

先决条件

• 一个 SimpleLogin 账户，以及专用 API 密钥。
• Git。
• 源码安装：Node.js 24.x、Corepack 和 pnpm 11.5.1。
• 容器安装：Docker 和 Docker Compose。
• 支持所选传输方式的 MCP 客户端：本地 stdio 或 Streamable HTTP。

本地 stdio

当客户端和服务端在同一台机器上运行时，建议从本地 stdio 开始：

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
corepack enable
pnpm install --filter simplelogin-mcp --frozen-lockfile
pnpm build

接下来，按照适用于你的 MCP 客户端的配置指南，将其指向 dist/index.js 的绝对路径，在其私有配置中设置 TRANSPORT=stdio 和 SL_API_KEY，重启客户端，并使用文档中介绍的只读调用验证工具发现。

Docker Compose

使用随附的 Compose 文件运行由运维人员管理的持久化服务：

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
cp .env.example .env
# Set SL_API_KEY and MCP_AUTH_TOKEN in .env
docker compose up -d
docker compose ps
curl http://localhost:3000/health

v1.0.4 的响应为 {"status":"ok","version":"1.0.4"}。

默认文件会拉取已发布的 GHCR 镜像，仅在 127.0.0.1 上发布主机端口，并且由于应用会在容器内绑定 0.0.0.0，因此需要设置 MCP_AUTH_TOKEN。请将 SIMPLELOGIN_MCP_IMAGE_TAG 固定为某个版本，以便重复部署。扩大主机绑定范围前，请参阅 Docker Compose 指南。

本地 Docker 构建

更改源代码时，请从检出目录构建容器，而不要拉取 GHCR 镜像：

docker compose -f docker-compose.local.yml up --build

直接使用 Node.js — Streamable HTTP

开发直接使用 Node.js 的 Streamable HTTP 时，请复制 .env.example，设置 SL_API_KEY，并仅在子 shell 中加载被忽略的文件：

corepack enable
pnpm install --filter simplelogin-mcp --frozen-lockfile
cp .env.example .env
pnpm build
(
  set -a
  . ./.env
  set +a
  TRANSPORT=http HOST=127.0.0.1 PORT=3000 pnpm start
)

MCP 端点为 POST http://127.0.0.1:3000/mcp；GET /health 仅用于检查进程是否正常运行。有关客户端身份验证和更广泛网络环境的要求，请参阅 Streamable HTTP 指南。

配置

通过环境变量提供配置，并在启动时进行验证。主要设置如下：

变量	用途
SL_API_KEY	必需的 SimpleLogin 凭据；授予完整账户控制权限。
TRANSPORT	字面值 stdio 或 http；默认为 http。
SL_API_URL	托管版或自托管 SimpleLogin Web 应用的源。
HOST / PORT	直接的 Streamable HTTP 监听器；默认为 127.0.0.1:3000。
MCP_AUTH_TOKEN	用于保护 POST /mcp 的独立 Bearer 令牌；正常的非回环地址启动时必需。

请参阅完整的配置参考，了解 Compose 端口发布、允许的浏览器源、超时、私有 CA 和代理变量。

获取 SimpleLogin API 密钥

在 SimpleLogin 控制面板中创建一个专用密钥，并妥善保密。请参阅 API 密钥指南，了解托管版和自托管实例的相关说明。

连接客户端

请使用维护中的客户端设置指南配置 Codex、Claude Code、Claude Desktop、VS Code 和 OpenCode。兼容性页面记录了当前证据的范围和局限。

客户端发现服务后，请提问：“能否向我展示 SimpleLogin 账户的使用情况？”预期调用的工具是 account_get_stats，这是一个无需参数的只读调用，会返回账户的汇总计数。调用成功即可验证客户端连接以及对 SimpleLogin 的访问权限；GET /health 仅检查 HTTP 服务是否正在运行。

自托管 SimpleLogin

将 SL_API_URL 设置为自托管 Web 应用的源，不要添加 /api 后缀，并在同一实例上创建 SL_API_KEY。私有 CA 和代理配置请参阅配置参考。兼容性取决于实例是否提供与上游兼容的 API 路径和响应结构。

故障排除

请从故障排除指南开始。请勿在日志或问题报告中包含 API 密钥、Bearer 令牌、授权标头、代理凭据、别名地址或邮箱地址。支持范围请参阅 SUPPORT.md。

开发

需要 Node.js 24.x 和 pnpm。

pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm lint
pnpm test
pnpm format:check

要启动监视服务器，请先将配置载入环境，然后运行 pnpm dev。本地 pnpm 命令不会自动载入 .env；直接运行 Node.js 示例展示了如何在子 shell 中载入它。

有关端点模式、目录生成、测试和拉取请求要求，请参阅 CONTRIBUTING.md。SimpleLogin 实时冒烟测试需要手动选择加入，因为它会创建临时别名；请使用 docs/live-smoke-test.md 并确认已完成清理。

架构

端点支持由常量、响应架构、SimpleLogin 客户端以及工具目录和注册逻辑共同实现。共享请求层负责处理身份验证、超时、错误规范化和响应验证。具体的变更模式请参阅 CONTRIBUTING.md，运行时请求流程请参阅工作原理。

安全

请将 SL_API_KEY 视为密码。本地 stdio 不会打开任何监听器。Streamable HTTP 默认绑定到 loopback，并拒绝在未通过身份验证的情况下正常启动非 loopback 服务。任何局域网或公网部署都应启用 MCP_AUTH_TOKEN，并在反向代理处终止 TLS。

报告漏洞前，请阅读 SECURITY.md。如有疑问或要报告非安全类 Bug，请参阅 SUPPORT.md。

贡献

欢迎贡献。在提交拉取请求前，请阅读 CONTRIBUTING.md。

许可证

MIT — 详见 LICENSE。