Skip to main content
Glama
AliMail Admin MCP

AliMail Admin MCP

by mfcompliance

alimail-admin-mcp

基于阿里邮箱开放平台 API 的 MCP(Model Context Protocol)服务。在 Claude、VS Code Copilot、Cursor 等 AI 客户端里,用自然语言管理企业邮箱的用户、部门、邮件组、公共通讯录、组织与域名,以及收信黑白名单、隔离区和审计日志。

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

特性

  • 66 个工具,分为 8 个工具集:

    • users:账号增删改查、别名、重置密码、邮箱设置、共享成员、安全手机、撤销登录态

    • departments:部门增删改查、层级链,以及可递归获取整棵部门树的组合工具

    • groups:邮件组增删改查与成员管理

    • contacts:公共联系人及分组管理,可递归获取分组树

    • org:组织信息、域名的添加 / 验证 / 删除

    • security:域级收信黑白名单、隔离区邮件的搜索 / 查看 / 放行 / 删除

    • audit:审计日志查询

    • login:生成免登录链接(默认不启用)

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

  • 破坏性操作需两步确认:先返回预览和一次性 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):

变量

默认值

说明

ALIMAIL_CLIENT_ID

—

必填,应用 ID

ALIMAIL_CLIENT_SECRET

—

必填,应用 Secret

ALIMAIL_API_BASE

https://alimail-cn.aliyuncs.com

API 地址,不同集群不能混用

ALIMAIL_READ_ONLY

true

设为 false 才会注册写操作和破坏性工具

ALIMAIL_TOOLSETS

除 login 外的全部工具集

启用的工具集,逗号分隔:users、departments、groups、contacts、org、security、audit、login;all 表示全部(含 login)

ALIMAIL_ALLOWED_DOMAINS

空(不限制)

限定可操作的邮箱域名,逗号分隔,子域名同样适用

ALIMAIL_MAX_QPS

20

本服务的请求速率上限(最大 40),需要给同域的其他应用留出余量

ALIMAIL_TIMEOUT_MS

15000

单次请求超时

ALIMAIL_AUDIT_LOG

空(输出到 stderr)

审计日志文件路径

MCP_HTTP_HOST

127.0.0.1(Docker 镜像内为 0.0.0.0)

HTTP 监听地址

MCP_HTTP_PORT

3000

HTTP 端口

MCP_AUTH_TOKEN

空

HTTP 模式下可选:设置后请求必须带 Authorization: Bearer <token>

MCP_ALLOWED_HOSTS

localhost,127.0.0.1,[::1]

允许的 Host 头,用于防御 DNS rebinding

LOG_LEVEL

info

debug / info / warn / error

运行

方式一:npx(推荐)

已发布到 npm:@mfcompliance/alimail-admin-mcp,同时收录于 MCP Registry(io.github.mfcompliance/alimail-admin-mcp)。需要 Node.js 20 或更高版本。

ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy npx -y @mfcompliance/alimail-admin-mcp --check   # 验证凭证(只换取 token,不调用业务接口)
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy npx -y @mfcompliance/alimail-admin-mcp --list-tools

也可以全局安装:npm i -g @mfcompliance/alimail-admin-mcp,之后直接运行 alimail-admin-mcp。

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

方式二:从源码运行

npm ci
npm run build
ALIMAIL_CLIENT_ID=xxx ALIMAIL_CLIENT_SECRET=yyy node dist/index.js --check

方式三:Docker

镜像由 GitHub Actions 自动构建并发布到 GitHub Container Registry,支持 linux/amd64 和 linux/arm64:

docker pull ghcr.io/mfcompliance/alimail-admin-mcp:latest

标签

含义

latest、X.Y.Z、X.Y(X 从 1.0 开始)

正式版本,在推送 vX.Y.Z 标签时发布

main

main 分支的最新构建

sha-<短提交号>

对应某次提交的构建

也可以在本地构建:

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

下文示例使用 GHCR 镜像。如果是本地构建,把镜像名换成 alimail-admin-mcp:local 即可。

# 验证凭证
docker run --rm -e ALIMAIL_CLIENT_ID=xxx -e ALIMAIL_CLIENT_SECRET=yyy ghcr.io/mfcompliance/alimail-admin-mcp:latest --check

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

docker run -i --rm -e ALIMAIL_CLIENT_ID -e ALIMAIL_CLIENT_SECRET ghcr.io/mfcompliance/alimail-admin-mcp:latest

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": "npx",
      "args": ["-y", "@mfcompliance/alimail-admin-mcp"],
      "env": {
        "ALIMAIL_CLIENT_ID": "${input:alimail-id}",
        "ALIMAIL_CLIENT_SECRET": "${input:alimail-secret}",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

使用 Docker 时,把 command/args 换成 "command": "docker", "args": ["run", "-i", "--rm", "-e", "ALIMAIL_CLIENT_ID", "-e", "ALIMAIL_CLIENT_SECRET", "-e", "ALIMAIL_READ_ONLY", "ghcr.io/mfcompliance/alimail-admin-mcp:latest"];从源码运行时,换成 "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": "npx",
      "args": ["-y", "@mfcompliance/alimail-admin-mcp"],
      "env": {
        "ALIMAIL_CLIENT_ID": "xxx",
        "ALIMAIL_CLIENT_SECRET": "yyy",
        "ALIMAIL_READ_ONLY": "true"
      }
    }
  }
}

工具一览

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

users

工具

说明

list_users

按 filter 查询用户,游标分页。filter 示例:(departmentId=xxx*)、(|(name=Jack)(email=*jack*))

get_user / get_users_by_ids

获取单个用户 / 批量获取(最多 100 个)

get_mailbox_settings

获取邮箱设置(外发限制、转发、附件大小等)

list_shared_members

查询共享 / 委托成员

check_shared_access

检查某用户能否访问指定共享账号

✏️ create_user

创建账号;不传密码时自动生成,并强制下次登录修改

✏️ update_user

更新资料、部门、状态(FREEZE 为冻结)

✏️ add_email_alias

添加别名

✏️ update_mailbox_settings

修改邮箱设置

✏️ add_shared_members / update_shared_members

添加 / 更新共享成员权限(LOGIN、SEND_AS、SEND_ON_BEHALF)

✏️ bind_security_phone

绑定安全手机

🔥 delete_user

删除账号(不可逆)

🔥 reset_password

重置密码(可自动生成)

🔥 remove_email_alias

删除别名

🔥 remove_shared_members

移除共享成员

🔥 unbind_security_phone

解绑安全手机

🔥 revoke_user_sessions

撤销全部登录态

departments

工具

说明

get_department

获取部门信息,$root 表示根部门

get_departments_by_ids

批量获取(最多 100 个)

list_sub_departments / list_department_users

直属子部门 / 直属成员(offset 分页)

get_department_chain

层级链(支持单个或批量)

get_department_tree

递归获取整棵部门树,自动分页;可设置深度、节点上限,可附带成员

✏️ create_department / update_department

创建 / 更新(修改 parentId 即为移动部门)

🔥 delete_department

删除部门;非空部门会删除失败,预览中会提示

groups

工具

说明

list_groups

按 filter 查询邮件组,游标分页。filter 示例:(name=*研发*)、(&(type=DYNAMIC)(status=FREEZE))

get_group

按 ID 或邮箱获取邮件组

list_group_members

查询成员邮箱(offset 分页,单页最多 10000)

✏️ create_group / update_group

创建 / 更新(发信权限、投递审核、冻结等)

✏️ add_group_members

批量添加成员(最多 50 个)

🔥 remove_group_members

批量移除成员

🔥 delete_group

删除邮件组

contacts

工具

说明

get_shared_contact

获取公共联系人

get_contact_folder / get_contact_folder_chain

获取分组 / 分组层级链,$root 表示根分组

list_contact_subfolders / list_folder_contacts

直属子分组 / 分组内联系人(offset 分页)

get_contact_folder_tree

递归获取整棵分组树,可附带联系人

✏️ create_shared_contact / update_shared_contact

创建 / 更新联系人(修改 folderId 即为移动)

✏️ create_contact_folder / update_contact_folder

创建 / 更新分组(修改 parentId 即为移动)

🔥 delete_shared_contacts

删除联系人(单次最多 20 个)

🔥 delete_contact_folder

删除分组,预览显示联系人数和子分组数

org

工具

说明

get_organization

获取组织信息

list_domains / get_domain

查询域名列表 / 单个域名(含域别名、MX 状态)

✏️ update_organization

更新组织名称、联系方式、默认域名等

✏️ add_domain / verify_domain

添加域名 / 验证域名所有权

🔥 delete_domain

删除域名;主域名无法删除,预览中会提示

security

工具

说明

list_allow_block_list

查询域级收信白名单 / 黑名单

search_quarantine_messages

按发件人、收件人、主题、时间搜索用户隔离区(隔离邮件保留 30 天)

get_quarantine_message / list_quarantine_attachments

隔离邮件详情 / 附件列表

get_quarantine_attachment_url

获取隔离附件的临时下载地址

🔥 add_allow_block_entries

添加黑白名单条目(邮箱、域名、IP、IP 段、IP 归属地),对全组织生效

🔥 remove_allow_block_entries

删除黑白名单条目

🔥 release_quarantine_message

放行隔离邮件,投递到收件人邮箱

🔥 delete_quarantine_messages

删除隔离邮件(移到已删除 / 企业回收站 / 永久删除)

audit

工具

说明

query_audit_logs

按时间、活动类型(登录、收发信、账号变更等)、操作者和属性查询审计日志

login

默认不启用,需要在 ALIMAIL_TOOLSETS 中显式加入 login(或使用 all),且需关闭只读模式。

工具

说明

🔥 create_login_link

生成一次性免登录链接(约 1 分钟有效),持有链接即可进入该用户邮箱

安全机制

两步确认

调用破坏性工具时:

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

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

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

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

其他

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

  • 设置 ALIMAIL_ALLOWED_DOMAINS 后,所有针对单个用户的操作都会检查目标所在域名。用 ID 定位用户时,服务会先查询出邮箱再做检查。创建用户、添加别名、共享成员中的地址也会检查。邮件组、隔离区、免登链接、按操作者查询审计日志,以及添加 / 验证 / 删除域名,同样按目标邮箱或域名检查。列表类查询(list_users、list_groups 等)、组织级设置(组织信息、收信黑白名单)、公共联系人以及邮件组成员地址不受此限制。

  • 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、tree(通用树遍历)及各工具集
  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 中注册。

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

发布

.github/workflows/docker.yml 的行为:

  • Pull Request:运行测试,并构建镜像,但不推送。

  • 推送到 main:测试通过后推送 main 和 sha-* 标签。

  • 推送 v* 标签:推送版本号标签和 latest,同时附带构建来源证明(build provenance attestation)。

.github/workflows/npm.yml 在推送 v* 标签时发布 npm 包:先校验标签与 package.json、server.json 版本一致,再通过 Trusted Publishing(OIDC,无需 NPM_TOKEN)发布,并附带 provenance。预发布版本(如 0.2.0-beta.1)使用 next 标签,不影响 latest。如果该版本已在 npm 上,会跳过 npm 发布,因此重跑 workflow 是安全的。

npm 发布成功后,同一个 workflow 会用 GitHub OIDC 登录 MCP Registry,把 server.json 发布为 io.github.mfcompliance/alimail-admin-mcp(预发布版本不发布)。Registry 通过 package.json 里的 mcpName 校验 npm 包归属,因此 mcpName 必须与 server.json 的 name 一致。

发布新版本的步骤:

npm version 0.3.0 --no-git-tag-version   # 同步修改 package.json、package-lock.json 和 server.json;再手动更新 CHANGELOG.md
git commit -am "chore: release v0.3.0"
git tag v0.3.0 && git push origin main v0.3.0

首次推送后,GHCR 上的包默认是私有的。如果要让别人免登录拉取,需要在仓库的 Packages → 包设置 → Change visibility 中改为 Public。

免责声明

  • 本项目为社区开发的非官方工具,与阿里巴巴集团、阿里云及阿里邮箱无任何隶属、合作或背书关系。“阿里邮箱”“Alibaba Mail”等名称和商标归其各自所有者所有,本项目仅用于说明兼容对象。

  • 本软件按“原样”提供,不附带任何明示或默示的担保,详见 MIT 许可。作者和贡献者不对因使用本软件导致的任何损失承担责任,包括数据丢失、账号误删或被停用、邮件服务中断、安全事件。

  • 写操作和破坏性操作可能由 AI 模型根据自然语言指令发起,模型可能误解指令或产生错误参数。两步确认、只读模式、域名限制等机制只能降低风险,不能完全消除风险。请先在测试域名或测试账号上验证,执行前仔细核对预览内容,并在生产环境中按最小权限原则配置应用权限。

  • 本工具会处理员工姓名、邮箱、手机号、登录记录等个人信息和企业数据。使用者应自行确保符合所在组织的内部制度和适用的法律法规,例如《个人信息保护法》《数据安全法》,并妥善保管应用凭证和审计日志。

  • 阿里邮箱开放平台的接口、权限和限额可能随时变化,以官方文档为准。

许可

MIT

Available Tools

11 tools
get_department获取部门信息A
Read-onlyIdempotent

根据部门 ID 获取部门信息;id 传 $root 返回组织根部门。

Inputs: id (required), select.

get_department_chain获取部门层级链A
Read-onlyIdempotent

获取从根部门到目标部门的完整层级链。传 id 查询单个,传 ids 批量查询(最多 100 个)。

Inputs: id, ids.

get_departments_by_ids批量获取部门信息A
Read-onlyIdempotent

根据部门 ID 列表批量获取部门信息(最多 100 个),不存在的 ID 不返回。

Inputs: ids (required), select.

get_department_tree获取部门树A
Read-onlyIdempotent

从指定部门(默认根部门)递归获取完整部门树,自动处理分页。可选包含每个部门的直属成员。大型组织请设置 maxDepth / maxNodes 控制规模,结果中 truncated=true 表示被截断。

Inputs: rootId, maxDepth, maxNodes, includeUsers, +1 more.

get_mailbox_settings获取邮箱设置A
Read-onlyIdempotent

获取用户邮箱设置(外部收发信限制、自动转发、附件大小、收件人数等)。字段多为可选字段,可用 select 指定,如 forbidSendMailToOutside,forwardingMode,attachmentSize。

Inputs: user (required), select.

get_user获取用户信息C
Read-onlyIdempotent

根据用户 ID 或邮箱获取用户详情。

Inputs: user (required), select.

get_users_by_ids批量获取用户信息A
Read-onlyIdempotent

根据用户 ID 列表批量获取用户信息(最多 100 个),不存在的 ID 不返回。

Inputs: ids (required), select.

list_department_users查询部门成员A
Read-onlyIdempotent

查询指定部门的直属成员(offset/limit 分页,limit 最大 100)。如需含子部门成员,可用 list_users 的 filter (departmentId=xxx*)。

Inputs: id (required), limit, offset, select, +1 more.

list_shared_members查询共享账号成员B
Read-onlyIdempotent

查询共享账号 / 委托账号的成员及其访问权限(LOGIN / SEND_AS / SEND_ON_BEHALF)与审批状态。

Inputs: user (required), limit, offset.

list_sub_departments查询子部门A
Read-onlyIdempotent

查询指定部门的直属子部门(offset/limit 分页,limit 最大 100)。需要整棵树请用 get_department_tree。

Inputs: id (required), limit, offset, select, +1 more.

list_users查询用户列表A
Read-onlyIdempotent

按 filter 表达式查询组织内用户,游标分页(单页最多 100)。 filter 支持字段:email、name、nickname、employeeNo、status、domain、employeeType、delegateType、departmentId、jobTitle、workLocation、homeLocation、info、managerId、isSharedWithOthers。 示例:(departmentId=xxx) 直属成员;(departmentId=xxx*) 含子部门;(|(name=Jack)(email=jack));(&(employeeType=SERVICE)(email=abc));(&(departmentId=xxx)(!(status=FREEZE)))。 返回 hasMore=true 时用 nextCursor 继续翻页。

Inputs: size, order, cursor, filter, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    The get/list department trio (get_department, get_departments_by_ids, get_department_chain) and the tree-vs-subdepartment pair (get_department_tree vs list_sub_departments) have some conceptual overlap, but descriptions explicitly cross-reference each other ("需要整棵树请用 get_department_tree") to route the agent correctly. Single-vs-batch (get_user vs get_users_by_ids) and user-vs-department listing are clearly distinguished.

    Naming Consistency5/5

    All 11 tools follow a strict verb_noun snake_case convention: list_*, get_*, with suffixes clearly indicating batch (_by_ids, _ids). No mixing of styles or casing.

    Tool Count5/5

    11 tools is well within the ideal 3-15 range for an org directory/mailbox admin server. Each tool earns its place by covering a distinct access pattern (single, batch, tree, filter, chain, settings).

    Completeness3/5

    The surface is entirely read-only: there is no create/update/delete for departments or users, and no update_mailbox_settings despite get_mailbox_settings existing, which is a notable gap for an 'Admin' server. Read coverage (single, batch, tree, filter, chain, shared accounts, mailbox settings) is otherwise solid.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Migadu email hosting services through natural language, including creating mailboxes, setting up aliases, configuring autoresponders, and handling bulk operations efficiently.
      35
      31 PyPI
      17
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to manage MSP-multi-tenant email security: organizations, domains, users, licensing, features, subscription packages, and email flow reporting.
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants and compatible clients to securely search, read, send, reply, forward, organize, and bulk-delete email across multiple mailboxes, with automatic SMTP configuration and AES-256-encrypted credential storage.
      931 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants and other MCP clients to manage mailboxes, domains, routing rules, app passwords, and account credit through the Purelymail API, with optional read-only exposure.
      19
      405 npm
      1
      MIT