alimail-admin-mcp

基于阿里邮箱开放平台 API 的 MCP（Model Context Protocol）服务。在 Claude、VS Code Copilot、Cursor 等 AI 客户端里，用自然语言管理企业邮箱的用户和部门。

⚠️ 本项目为非官方实现，与阿里云 / 阿里邮箱无隶属关系。它使用的应用凭证具有企业邮箱管理员级别的权限，请在充分理解风险后使用。

特性

• 27 个工具，分为 users、departments 两个工具集：账号增删改查、别名、重置密码、邮箱设置、共享成员、安全手机、撤销登录态；部门增删改查、层级链，以及可递归获取整棵部门树的组合工具

• 默认只读：ALIMAIL_READ_ONLY=true 时只注册 11 个查询工具

• 破坏性操作需两步确认：先返回预览和一次性 confirmToken，确认后才执行

• 域名范围限制：ALIMAIL_ALLOWED_DOMAINS 可限定只能操作指定域名下的账号

• 审计日志：所有写操作都记录为 JSON 行，密码、token 等敏感字段自动脱敏

• 稳健的 API 客户端：token 缓存并提前刷新；令牌桶限流；429/5xx 自动退避重试，非幂等写操作不盲目重试；错误统一格式化并附带修复提示

• 两种传输方式：stdio（默认）与 Streamable HTTP（--http）

• Resources：alimail://departments/tree、alimail://users/{email}；Prompts：onboard_employee（入职）、offboard_employee（离职）

Related MCP server: proofpoint-essentials-mcp

准备工作：创建阿里邮箱应用

1. 以管理员身份登录阿里邮箱域管后台，进入 高级应用 → API 开放平台（或“应用管理”），创建应用。

2. 按最小权限原则授予用户、部门相关的 API 权限。只读场景只授读权限；需要写操作再授读写权限。权限名称以后台实际列出的为准。

3. 记录应用的 client_id 与 client_secret。

4. 确认企业所在集群的 API 地址（默认 https://alimail-cn.aliyuncs.com）。

免费版阿里邮箱不支持 API 开放平台。单个域内所有应用的 API 调用合计不能超过 40 次/秒。

配置

所有配置都通过环境变量提供（可参考 .env.example）：

运行

方式一：从源码运行

npm ci
npm run build
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy node dist/index.js --check   # 验证凭证（只换取 token，不调用业务接口）
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy node dist/index.js --list-tools

命令行参数：--http、--host、--port、--check、--list-tools、--version、--help。

方式二：Docker（本地构建）

docker build -t alimail-admin-mcp:local .

# 验证凭证
docker run --rm -e ALIMAIL_CLIENT_ID=xxx -e ALIMAIL_CLIENT_SECRET=yyy alimail-admin-mcp:local --check

stdio 模式：由 MCP 客户端负责拉起容器，必须带 -i：

docker run -i --rm -e ALIMAIL_CLIENT_ID -e ALIMAIL_CLIENT_SECRET alimail-admin-mcp:local

HTTP 模式：作为常驻服务运行：

cp .env.example .env    # 填入凭证
docker compose up -d --build
curl http://localhost:3000/healthz

docker-compose.yml 默认只把端口发布在 127.0.0.1 上，MCP 地址为 http://localhost:3000/mcp。

客户端配置

VS Code（.vscode/mcp.json）

使用 inputs 在运行时输入密钥，避免把密钥写进配置文件：

{
  "inputs": [
    { "id": "alimail-id", "type": "promptString", "description": "AliMail Client ID" },
    { "id": "alimail-secret", "type": "promptString", "description": "AliMail Client Secret", "password": true }
  ],
  "servers": {
    "alimail-admin": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ALIMAIL_CLIENT_ID", "-e", "ALIMAIL_CLIENT_SECRET", "-e", "ALIMAIL_READ_ONLY", "alimail-admin-mcp:local"],
      "env": {
        "ALIMAIL_CLIENT_ID": "${input:alimail-id}",
        "ALIMAIL_CLIENT_SECRET": "${input:alimail-secret}",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

如果不用 Docker，把 command/args 换成 "command": "node", "args": ["/绝对路径/alimail-admin-mcp/dist/index.js"]。

连接 HTTP 模式的服务：

{
  "servers": {
    "alimail-admin": { "type": "http", "url": "http://localhost:3000/mcp" }
  }
}

Claude Desktop / Cursor / Cline

{
  "mcpServers": {
    "alimail-admin": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ALIMAIL_CLIENT_ID", "-e", "ALIMAIL_CLIENT_SECRET", "-e", "ALIMAIL_READ_ONLY", "alimail-admin-mcp:local"],
      "env": {
        "ALIMAIL_CLIENT_ID": "xxx",
        "ALIMAIL_CLIENT_SECRET": "yyy",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

工具一览

✏️ 表示写操作（仅在 ALIMAIL_READ_ONLY=false 时注册），🔥 表示破坏性操作（同样需要关闭只读模式，并且需要两步确认）。

users

departments

安全机制

两步确认

调用破坏性工具时：

1. 第一次调用（不带 confirm）不会执行操作。它返回 status: "confirmation_required"，同时附带目标对象的预览（例如被删除用户的姓名、邮箱、状态）和一个 confirmToken。

2. AI 必须把预览展示给用户，并取得明确同意。

3. 第二次调用使用完全相同的参数，并带上 confirm: true 和 confirmToken，这时才真正执行。

confirmToken 只能使用一次，5 分钟后过期，并与工具名和参数绑定：换了目标或修改了参数，token 即失效。

其他

• 自动生成的密码只在执行结果中出现一次，不会写入日志或审计记录。

• 设置 ALIMAIL_ALLOWED_DOMAINS 后，所有针对单个用户的操作都会检查目标所在域名。用 ID 定位用户时，服务会先查询出邮箱再做检查。创建用户、添加别名、共享成员中的地址也会检查。列表类查询（list_users 等）不受此限制。

• HTTP 模式：

  • 默认只监听 127.0.0.1，并校验 Host 头以防御 DNS rebinding。

  • 如果监听在非回环地址上又没有设置 MCP_AUTH_TOKEN，启动时会输出警告。

  • 不要把未加认证的端口暴露到局域网或公网：能访问这个端口的人，就能以邮箱管理员身份执行操作。

• HTTP 模式是无状态的：每个请求都会新建 MCP 会话。token 缓存、限流、确认令牌和审计日志在进程内共享。

开发

npm ci
npm run typecheck
npm test          # vitest；所有 HTTP 请求均为模拟，不访问真实环境
npm run build
npm run inspect   # 使用 MCP Inspector 调试（需先设置凭证环境变量）

目录结构：

src/
  index.ts            CLI 入口
  config.ts           环境变量校验
  server.ts           组装 McpServer
  client/             token、限流、HTTP、分页、错误
  guard/              两步确认、域名范围、脱敏、审计
  tools/              registry + users + departments
  resources/ prompts/
  transports/         stdio、Streamable HTTP
test/                 单元测试与端到端测试（InMemory 及 HTTP）

新增工具集（例如邮件组、公共联系人、隔离区）的步骤：

1. 在 src/config.ts 的 TOOLSETS 中登记名称。

2. 新建 src/tools/<name>.ts，用 defineTool 定义工具。

3. 在 src/server.ts 的 ALL_TOOLS 中注册。

接口的字段、分页方式和所需权限，请以官方文档为准。

许可

MIT