钉钉机器人 MCP

钉钉机器人 MCP 服务器。通过 MCP 协议实现 AI 助手发送钉钉单聊和群聊消息，支持 文本、Markdown、图片、链接、ActionCard、文件、语音、视频 共 8 种消息类型，可通过 userId、姓名或 批量 userId 发送，最多单次 20 人。

![License: MIT](https://opensource.org/licenses/MIT)

---

功能

| 功能 | 说明 | |---|---| | 多消息类型 | 文本、Markdown、图片、链接、ActionCard、文件、语音、视频 | | 单聊消息 | 发送多种类型消息给指定用户 | | 群聊消息 | 发送多种类型消息到指定群 | | 媒体上传 | 上传本地文件获取 mediaId，用于图片/文件/语音/视频消息 | | 按 userId 发送 | 直接指定钉钉用户 ID（兼容旧用法） | | 按姓名发送 | 输入中文姓名，自动查找 userId 并发送 | | 批量发送 | 一次发送给最多 20 个用户 | | 重名检测 | 多人同名时拒绝发送，列出所有重复的 userId |

---

前置要求

| 项目 | 要求 | |---|---| | Node.js | >= 18.0.0 | | 钉钉应用 | 企业内部应用（机器人） |

---

第一步：创建钉钉应用

登录钉钉开放平台，进入「应用开发」→「企业内部应用」
创建应用，类型选 「机器人」
在「凭证与基础信息」页面获取：

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"
      }
    }
  }
}

| 环境变量 | 必填 | 说明 | |---|---|---| | DINGTALK_APP_KEY | ✅ | 钉钉应用 AppKey | | DINGTALK_APP_SECRET | ✅ | 钉钉应用 AppSecret |

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

---

使用指南

MCP 工具清单

| 工具名 | 功能 | |---|---| | send_dingtalk_single_message | 发送单聊消息（支持 8 种消息类型） | | send_dingtalk_group_message | 发送群聊消息（支持 8 种消息类型） | | upload_dingtalk_media | 上传媒体文件，获取 mediaId |

单聊消息参数

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | msgtype | string | 否（默认 text） | 消息类型：text / markdown / image / link / actionCard_single / actionCard_multi / file / audio / video | | userId | string | 三选一 | 单个用户 ID | | userIds | string[] | 三选一 | 多个用户 ID（最多 20 个） | | userName | string | 三选一 | 用户中文姓名（精确匹配） |

各消息类型额外参数：

| msgtype | 额外必填参数 | 可选参数 | |---|---|---| | text | content (文本内容) | — | | markdown | title (标题), text (Markdown正文) | — | | image | photoURL (图片URL或mediaId) | — | | link | title, text, messageUrl | picUrl (预览图) | | actionCard_single | title, text, singleTitle, singleURL | btnOrientation (0竖/1横) | | actionCard_multi | title, text, btns[] (按钮数组, 1-6个) | btnOrientation | | file | mediaId, fileName, fileType | — | | audio | mediaId, duration (毫秒) | — | | video | videoMediaId, picMediaId, duration (秒) | videoType, width, height |

群聊消息参数

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | chatId | string | ✅ | 群聊 openConversationId | | msgtype | string | 否（默认 text） | 消息类型（同单聊） |

其余参数与单聊消息各类型一致。

上传媒体文件参数

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | filePath | string | ✅ | 本地文件绝对路径 | | mediaType | string | ✅ | image / voice / video / file |

| mediaType | 支持格式 | 大小限制 | |---|---|---| | image | jpg, png, gif, bmp | 20MB | | voice | amr, mp3, wav | 2MB | | video | mp4 | 20MB | | file | doc, docx, xls, xlsx, ppt, pptx, zip, pdf, rar | 20MB |

使用示例

示例 1：发送文本（向后兼容） `` 给张三发消息，userId: "204457105626433998"，内容：明天的会议改到下午3点 ``

示例 2：按姓名发送 `` 通过钉钉给朱育敏发消息，内容是：请查收本周的测试报告 ``

示例 3：发送 Markdown `` 通过钉钉给 userId "011950195121139389" 发 markdown 消息，标题：周报提醒，text：请于周五前提交周报\n\n- 本周工作总结\n- 下周计划 ``

示例 4：上传并发送图片 `` 先把 D:\screenshot.png 上传到钉钉（mediaType: image），拿到 mediaId 后通过钉钉发给朱育敏，msgtype 用 image ``

示例 5：发送 ActionCard `` 给 userId "011950195121139389" 发 actionCard，msgtype: actionCard_single，title：新版本发布，text：## v2.0 已上线\n\n新增多消息类型支持，singleTitle：查看详情，singleURL：https://github.com ``

示例 6：批量发送 `` 通过钉钉给以下用户发消息： userIds: ["204457105626433998", "481029384729103847"] msgtype: text, content：全员通知：明天下午3点系统升级维护 ``

---

行为说明

姓名查找机制

首次按姓名发送时，MCP 服务器会遍历企业所有部门来构建姓名→userId 索引（耗时约 5~10 秒，取决于企业规模）
索引缓存 5 分钟，缓存期内后续查找 < 1ms
需要 通讯录部门信息读权限 + 通讯录成员信息读权限

重名处理

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

批量限制

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

---

获取 userId / chatId

获取自己的 userId

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

点击头像 → 个人信息
长按或点击「复制」你的 userId（视版本而定）
或者直接用姓名发送给自己

获取他人的 userId

使用本 MCP 的 按姓名发送 功能自动查找
或者登录钉钉管理后台 → 通讯录 → 用户详情页 URL 中包含 userId

获取 chatId（群聊 openConversationId）

在钉钉群设置 → 群机器人 → 查看机器人详情
或通过钉钉开放平台 API 获取

---

故障排查

问题 1：MCP 工具未显示

检查 ~/.workbuddy/mcp.json 路径是否正确
确认 node 命令可用（node --version）
断开钉钉连接器 → 重新启用

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

确认已开通「通讯录部门信息读权限」和「通讯录成员信息读权限」
断开再重新启用钉钉连接器使权限生效
确认姓名与钉钉通讯录中的完全一致

问题 3：消息发送失败

检查 AppKey / AppSecret 是否正确
确认「企业机器人消息推送」权限已开通
确认 userId 有效且该用户在企业可见范围内

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

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

---

技术栈

TypeScript
@modelcontextprotocol/sdk
axios
钉钉开放平台 API（新版 v1.0）

API 说明

| 操作 | API | |---|---| | 获取 Token | POST /v1.0/oauth2/accessToken | | 单聊消息 | POST /v1.0/robot/oToMessages/batchSend | | 群聊消息 | POST /v1.0/robot/groupMessages/send | | 上传媒体 | POST /oapi.dingtalk.com/media/upload | | 部门列表 | GET /oapi.dingtalk.com/department/list | | 部门成员 | GET /oapi.dingtalk.com/user/simplelist |

许可证

MIT

DingTalk Robot MCP