钉钉机器人 MCP

钉钉机器人 MCP 服务器。通过 MCP 协议实现 AI 助手发送钉钉单聊和群聊消息，支持通过 userId、姓名 或 批量 userId 发送，最多单次 20 人。

功能

Related MCP server: Telegram Bot MCP

前置要求

第一步：创建钉钉应用

1. 登录 钉钉开放平台，进入「应用开发」→「企业内部应用」

2. 创建应用，类型选 「机器人」

3. 在「凭证与基础信息」页面获取：

   • AppKey（应用的唯一标识）

   • AppSecret（应用的密钥）

第二步：开通钉钉权限

基础权限（必须）

确保应用已开通 「企业机器人消息推送」 权限。这是发送消息的基础权限，通常在创建机器人应用时默认开通。

验证方法：在应用详情页 → 「权限管理」 → 确认存在「企业机器人消息推送」。

按姓名发送权限（可选）

如果希望通过中文姓名发送消息（非必须，仅 userId 发送不需要），还需开通：

注意：「权限管理」入口在钉钉开放平台应用详情页的左侧菜单中，不同版本后台界面可能略有不同。如果找不到，试试「开发管理」→「权限管理」。

第三步：安装 & 配置

npm 全局安装（推荐）

npm install -g dingtalk-mcp-server

安装后运行配置向导：

dingtalk-mcp-server-config

向导会引导你输入 AppKey / AppSecret 并自动写入 WorkBuddy 配置。

手动配置

编辑 ~/.workbuddy/mcp.json：

{
  "mcpServers": {
    "dingtalk": {
      "command": "node",
      "args": [
        "C:\\path\\to\\dingtalk-mcp-server\\dist\\index.js"
      ],
      "env": {
        "DINGTALK_APP_KEY": "你的AppKey",
        "DINGTALK_APP_SECRET": "你的AppSecret"
      }
    }
  }
}

配置完成后，断开并重新启用钉钉连接器即可生效。

使用指南

MCP 工具清单

单聊消息参数

群聊消息参数

使用示例

示例 1：按 userId 发送

给张三发消息，userId: "204457105626433998"，内容：明天的会议改到下午3点

示例 2：按姓名发送

通过钉钉给朱育敏发消息，内容是：请查收本周的测试报告

示例 3：批量发送

通过钉钉给以下用户发消息：
userIds: ["204457105626433998", "481029384729103847"]
内容：全员通知：明天下午3点系统升级维护

示例 4：群聊消息

发送钉钉群消息，chatId: "cidXXXXXXXXX"，内容：本周会议纪要已更新

行为说明

姓名查找机制

• 首次按姓名发送时，MCP 服务器会遍历企业所有部门来构建姓名→userId 索引（耗时约 5~10 秒，取决于企业规模）

• 索引缓存 5 分钟，缓存期内后续查找 < 1ms

• 需要 通讯录部门信息读权限 + 通讯录成员信息读权限

重名处理

用户 "张伟" 在企业中有 3 个重名记录
→ 发送失败，错误信息列出 3 个 userId
→ 用户需改用 userId 指定具体接收人

批量限制

单次最多发送给 20 个用户，超出会报错。如需发送给更多人，请分批调用。

获取 userId / chatId

获取自己的 userId

最常见的场景是给自己发消息。在钉钉客户端中：

1. 点击头像 → 个人信息

2. 长按或点击「复制」你的 userId（视版本而定）

3. 或者直接用姓名发送给自己

获取他人的 userId

1. 使用本 MCP 的 按姓名发送 功能自动查找

2. 或者登录钉钉管理后台 → 通讯录 → 用户详情页 URL 中包含 userId

获取 chatId（群聊 openConversationId）

1. 在钉钉群设置 → 群机器人 → 查看机器人详情

2. 或通过钉钉开放平台 API 获取

故障排查

问题 1：MCP 工具未显示

1. 检查 ~/.workbuddy/mcp.json 路径是否正确

2. 确认 node 命令可用（node --version）

3. 断开钉钉连接器 → 重新启用

问题 2：按姓名发送报「未找到」

• 确认已开通「通讯录部门信息读权限」和「通讯录成员信息读权限」

• 断开再重新启用钉钉连接器使权限生效

• 确认姓名与钉钉通讯录中的完全一致

问题 3：消息发送失败

• 检查 AppKey / AppSecret 是否正确

• 确认「企业机器人消息推送」权限已开通

• 确认 userId 有效且该用户在企业可见范围内

问题 4：发送成功但对方收不到

• 确认该用户在应用的「可见范围」内

• 应用需要在「部署与发布」中设置可见范围为「全部员工」或包含目标用户

技术栈

• TypeScript

• @modelcontextprotocol/sdk

• axios

• 钉钉开放平台 API（新版 v1.0）

API 说明

许可证

MIT