dws-cli-mcp 使用手册

基于 DingTalk Workspace CLI (dws) 的 MCP Server，让 AI Agent 通过自然语言操作钉钉全套功能。

目录

• 安装与配置

• 工具总览

• 使用用例

  • 通讯录

  • 发消息给用户 / 群聊

  • 机器人 & Webhook 消息

  • 消息查询与搜索

  • 群聊管理

  • 日历与日程

  • 待办任务

  • 审批

  • 考勤

  • DING 消息

  • 日志（日报 / 周报）

  • AI 表格

  • 文档

  • 钉盘

  • AI 听记

  • 邮箱

  • 在线电子表格

  • 知识库

  • 开发者文档 & 错误诊断

  • AI 搜问

  • Schema 自省

• 常见组合工作流

Related MCP server: mdymcp

安装与配置

前置条件

1. 安装 dws CLI：

   curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

2. 登录授权：

   dws auth login

3. 确认 Node.js >= 18：

   node -v

安装依赖

克隆或下载本项目后，在项目目录执行：

npm install

配置 MCP Server

在 ~/.kiro/settings/mcp.json（或对应 AI 工具的 MCP 配置文件）中添加：

{
  "mcpServers": {
    "dws-cli": {
      "command": "node",
      "args": ["/Users/betty/dws-cli-mcp/server-dws-cli-mcp.mjs"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

重启 AI 工具后即可使用。

工具总览

使用用例

通讯录

搜索用户

自然语言提示：

帮我找一下叫"张三"的同事，我需要他的 userId

调用工具： dingtalk_contact_user_search

{
  "query": "张三"
}

根据手机号查找用户

自然语言提示：

手机号 13800138000 是谁？

调用工具： dingtalk_contact_user_search_mobile

{
  "mobile": "13800138000"
}

获取用户详细信息

自然语言提示：

告诉我 userId 为 user123 和 user456 的员工信息

调用工具： dingtalk_contact_user_get

{
  "user_ids": "user123,user456"
}

查看我自己的信息

自然语言提示：

我的钉钉账号信息是什么？我的 userId 是什么？

调用工具： dingtalk_contact_user_get_self

{}

搜索部门

自然语言提示：

帮我找一下"技术部"的部门 ID

调用工具： dingtalk_contact_dept_search

{
  "keyword": "技术部"
}

列出部门成员

自然语言提示：

列出研发一部（dept_id: dept001）的所有成员

调用工具： dingtalk_contact_dept_list_members

{
  "dept_id": "dept001"
}

发消息给用户 / 群聊

提示： 发消息前需要先知道 conversation_id（会话 ID）。可先用 dingtalk_chat_search 搜索群聊，或用 dingtalk_contact_user_search 找到用户后通过单聊会话 ID 发送。

给单个用户发消息

自然语言提示：

给张三发一条消息，告诉他今天下午 3 点开会

步骤 1 — 查找张三的会话 ID：

调用工具： dingtalk_contact_user_search

{
  "query": "张三"
}

步骤 2 — 发送消息：

调用工具： dingtalk_chat_send_message

{
  "conversation_id": "<张三的单聊 conversation_id>",
  "text": "你好，今天下午 3 点有个会议，请准时参加。"
}

给群聊发消息

自然语言提示：

在"项目Alpha讨论群"里发一条公告：明天上午 10 点代码冻结

步骤 1 — 搜索群聊：

调用工具： dingtalk_chat_search

{
  "keyword": "项目Alpha讨论群"
}

步骤 2 — 发送消息：

调用工具： dingtalk_chat_send_message

{
  "conversation_id": "<群聊 conversation_id>",
  "text": "【公告】明天上午 10:00 代码冻结，请各位提前完成提交。"
}

给多个用户逐一发消息

自然语言提示：

通知技术部所有成员：今晚有紧急发布

步骤 1 — 获取部门成员：

调用工具： dingtalk_contact_dept_list_members

{
  "dept_id": "dept_tech"
}

步骤 2 — 依次发送消息（循环调用）：

调用工具： dingtalk_chat_send_message

{
  "conversation_id": "<每位成员的单聊 conversation_id>",
  "text": "今晚有紧急发布，请关注群内通知，保持待命。"
}

机器人 & Webhook 消息

以机器人身份发群消息

自然语言提示：

用我的构建通知机器人，在"CI/CD 监控群"里发一条构建成功的消息

调用工具： dingtalk_chat_send_by_bot

{
  "robot_code": "dingxxxxxxxxxxxxxxxx",
  "group_id": "cidxxxxxxxxxxxxxxxx",
  "text": "✅ 构建成功！分支: main | 版本: v2.3.1 | 耗时: 3m12s"
}

通过 Webhook 发消息

自然语言提示：

通过 Webhook 向监控群发告警：数据库连接数超过阈值

调用工具： dingtalk_chat_send_by_webhook

{
  "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=xxxxx",
  "text": "⚠️ 告警：数据库连接数已达 480/500，请立即检查！"
}

消息查询与搜索

查看最近消息

自然语言提示：

帮我看看"项目Alpha讨论群"最近 30 条消息说了什么

调用工具： dingtalk_chat_message_list

{
  "conversation_id": "cidxxxxxxxxxxxxxxxx",
  "count": 30
}

搜索关键词消息

自然语言提示：

帮我搜索所有提到"上线时间"的消息

调用工具： dingtalk_chat_message_search

{
  "keyword": "上线时间"
}

查看 @我 的消息

自然语言提示：

最近有哪些消息 @ 了我？

调用工具： dingtalk_chat_message_list_mentions

{
  "count": 20
}

查看未读消息

自然语言提示：

我现在有哪些未读消息？

调用工具： dingtalk_chat_message_list_unread

{}

查看某段时间内所有消息

自然语言提示：

给我汇总一下今天所有会话的消息

调用工具： dingtalk_chat_message_list_all

{
  "start_time": "2026-06-17T00:00:00+08:00",
  "end_time": "2026-06-17T23:59:59+08:00"
}

群聊管理

创建群聊

自然语言提示：

帮我创建一个"Q3 冲刺计划群"，成员包括 user001、user002、user003

调用工具： dingtalk_chat_group_create

{
  "name": "Q3 冲刺计划群",
  "user_ids": "user001,user002,user003"
}

查看群成员

自然语言提示：

看看"项目Alpha讨论群"里有哪些人

调用工具： dingtalk_chat_group_members

{
  "conversation_id": "cidxxxxxxxxxxxxxxxx"
}

添加成员到群

自然语言提示：

把新来的同事 user999 加到"项目Alpha讨论群"里

调用工具： dingtalk_chat_group_members_add

{
  "conversation_id": "cidxxxxxxxxxxxxxxxx",
  "user_ids": "user999"
}

日历与日程

查看今日日程

自然语言提示：

我今天有什么日程安排？

调用工具： dingtalk_calendar_event_list

{
  "start_time": "2026-06-17T00:00:00+08:00",
  "end_time": "2026-06-17T23:59:59+08:00"
}

创建会议

自然语言提示：

明天下午 2 点安排一个"Q3 需求评审"，邀请 user001 和 user002，开 1 小时

调用工具： dingtalk_calendar_event_create

{
  "summary": "Q3 需求评审",
  "start_time": "2026-06-18T14:00:00+08:00",
  "end_time": "2026-06-18T15:00:00+08:00",
  "attendees": "user001,user002",
  "description": "评审 Q3 季度的产品需求，请提前准备 PRD"
}

查询多人忙闲时间

自然语言提示：

我想约 user001 和 user002 开会，本周他们什么时候有空？

步骤 1 — 查询忙闲：

调用工具： dingtalk_calendar_busy_search

{
  "user_ids": "user001,user002",
  "start_time": "2026-06-17T09:00:00+08:00",
  "end_time": "2026-06-21T18:00:00+08:00"
}

智能推荐会议时间

自然语言提示：

帮我找一个本周所有人都有空的 1 小时会议时间槽，参与者 user001、user002、user003

调用工具： dingtalk_calendar_event_suggest

{
  "attendees": "user001,user002,user003",
  "duration_minutes": 60,
  "start_time": "2026-06-17T09:00:00+08:00",
  "end_time": "2026-06-21T18:00:00+08:00"
}

删除日程

自然语言提示：

取消明天下午的"Q3 需求评审"

调用工具： dingtalk_calendar_event_delete

{
  "event_id": "event_xxxxxxxx"
}

待办任务

查看我的待办

自然语言提示：

我现在有哪些未完成的待办？

调用工具： dingtalk_todo_task_list

{
  "done": false
}

创建待办

自然语言提示：

帮我建一个待办：本周五前完成接口联调，指派给 user001

调用工具： dingtalk_todo_task_create

{
  "title": "完成接口联调",
  "due_time": "2026-06-20T18:00:00+08:00",
  "executors": "user001",
  "description": "与前端完成所有 REST API 的联调工作，完成冒烟测试"
}

标记待办完成

自然语言提示：

把"完成接口联调"这个待办标记为已完成

调用工具： dingtalk_todo_task_done

{
  "task_id": "task_xxxxxxxx",
  "done": true
}

修改待办截止时间

自然语言提示：

把 task_xxxxxxxx 的截止时间延到下周一

调用工具： dingtalk_todo_task_update

{
  "task_id": "task_xxxxxxxx",
  "due_time": "2026-06-23T18:00:00+08:00"
}

删除待办

自然语言提示：

删掉 task_xxxxxxxx 这个待办

调用工具： dingtalk_todo_task_delete

{
  "task_id": "task_xxxxxxxx"
}

审批

查看待我审批的列表

自然语言提示：

我现在有哪些审批需要处理？

调用工具： dingtalk_oa_approval_list_pending

{}

查看审批单详情

自然语言提示：

帮我看一下审批单 inst_xxxxxxxx 的内容

调用工具： dingtalk_oa_approval_detail

{
  "instance_id": "inst_xxxxxxxx"
}

审批通过

自然语言提示：

同意审批单 inst_xxxxxxxx，备注"同意，流程符合规范"

步骤 1 — 获取任务 ID：

调用工具： dingtalk_oa_approval_tasks

{}

步骤 2 — 审批通过：

调用工具： dingtalk_oa_approval_approve

{
  "instance_id": "inst_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "remark": "同意，流程符合规范"
}

审批拒绝

自然语言提示：

拒绝审批单 inst_xxxxxxxx，原因是预算超标

调用工具： dingtalk_oa_approval_reject

{
  "instance_id": "inst_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "remark": "预算超出本季度上限，请重新申请"
}

考勤

查询打卡记录

自然语言提示：

查一下我本周的打卡记录

调用工具： dingtalk_attendance_record_get

{
  "start_date": "2026-06-15",
  "end_date": "2026-06-21"
}

查看考勤汇总

自然语言提示：

查一下我 6 月份的考勤汇总，有没有迟到早退

调用工具： dingtalk_attendance_summary

{
  "year_month": "2026-06"
}

DING 消息

发送高优先级通知

自然语言提示：

紧急通知 user001 和 user002：服务器宕机，需要立刻处理！（用电话方式）

调用工具： dingtalk_ding_message_send

{
  "receiver_ids": "user001,user002",
  "text": "【紧急】生产服务器出现宕机，请立即登录处理！",
  "remind_type": 4
}

remind_type：1 = 应用内通知，2 = 短信，4 = 电话

日志（日报 / 周报）

查看可用日志模板

自然语言提示：

我可以用哪些日志模板？

调用工具： dingtalk_report_template_list

{}

查看模板字段结构

自然语言提示：

日报模板的字段有哪些？

调用工具： dingtalk_report_template_detail

{
  "template_name": "日报"
}

提交日报

自然语言提示：

帮我提交今天的日报：今天完成了登录模块的接口开发，明天开始做权限管理

调用工具： dingtalk_report_create

{
  "template_name": "日报",
  "contents": "[{\"key\":\"今日工作\",\"value\":\"完成登录模块接口开发，联调通过\"},{\"key\":\"明日计划\",\"value\":\"开始权限管理模块开发\"}]"
}

查看收到的日志

自然语言提示：

看看团队成员最近给我发的日志

调用工具： dingtalk_report_list

{
  "count": 10
}

查看我发出的日志

自然语言提示：

我最近提交了哪些日志？

调用工具： dingtalk_report_sent

{
  "count": 10
}

AI 表格

列出我的 AI 表格

自然语言提示：

我有哪些 AI 表格？

调用工具： dingtalk_aitable_base_list

{}

搜索 AI 表格

自然语言提示：

帮我找名字包含"OKR"的 AI 表格

调用工具： dingtalk_aitable_base_search

{
  "keyword": "OKR"
}

查询表格记录

自然语言提示：

查一下"项目跟踪表"里状态为"进行中"的所有任务

步骤 1 — 找到 Base ID：

调用工具： dingtalk_aitable_base_search

{ "keyword": "项目跟踪表" }

步骤 2 — 获取数据表列表：

调用工具： dingtalk_aitable_table_get

{ "base_id": "bseXXXXXXXXXX" }

步骤 3 — 查询记录：

调用工具： dingtalk_aitable_record_query

{
  "base_id": "bseXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXX",
  "filter": "{状态}=\"进行中\"",
  "limit": 50
}

新增记录

自然语言提示：

在"Bug 跟踪表"里新增一条记录：标题"登录页白屏"，优先级"高"，负责人"张三"

调用工具： dingtalk_aitable_record_create

{
  "base_id": "bseXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXX",
  "records": "[{\"fields\":{\"标题\":\"登录页白屏\",\"优先级\":\"高\",\"负责人\":\"张三\"}}]"
}

更新记录

自然语言提示：

把 recXXXXXX 这条 Bug 的状态改为"已修复"

调用工具： dingtalk_aitable_record_update

{
  "base_id": "bseXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXX",
  "records": "[{\"recordId\":\"recXXXXXX\",\"fields\":{\"状态\":\"已修复\"}}]"
}

删除记录

自然语言提示：

删除表格中 recXXXXXX 和 recYYYYYY 这两条记录

调用工具： dingtalk_aitable_record_delete

{
  "base_id": "bseXXXXXXXXXX",
  "table_id": "tblXXXXXXXXXX",
  "record_ids": "recXXXXXX,recYYYYYY"
}

文档

搜索文档

自然语言提示：

帮我找所有包含"架构设计"的文档

调用工具： dingtalk_doc_search

{
  "query": "架构设计"
}

读取文档内容

自然语言提示：

读取"Q3 技术规划"这篇文档的内容

调用工具： dingtalk_doc_read

{
  "doc_id": "doc_xxxxxxxx"
}

创建文档

自然语言提示：

在"团队文档"文件夹下创建一篇新文档"6月复盘总结"

调用工具： dingtalk_doc_create

{
  "title": "6月复盘总结",
  "parent_id": "folder_xxxxxxxx",
  "content": "## 本月亮点\n\n## 待改进项\n\n## 下月计划\n"
}

更新文档内容

自然语言提示：

把"6月复盘总结"这篇文档的内容替换为新版本

调用工具： dingtalk_doc_update

{
  "doc_id": "doc_xxxxxxxx",
  "content": "## 本月亮点\n- 完成了用户中心重构\n\n## 待改进项\n- 测试覆盖率不足\n"
}

钉盘

列出文件

自然语言提示：

看看钉盘根目录下有哪些文件

调用工具： dingtalk_drive_list

{}

获取文件下载链接

自然语言提示：

给我获取"年度报告.pdf"的下载链接

调用工具： dingtalk_drive_download

{
  "file_id": "file_xxxxxxxx"
}

创建文件夹

自然语言提示：

在钉盘根目录创建一个叫"2026年报告"的文件夹

调用工具： dingtalk_drive_mkdir

{
  "name": "2026年报告"
}

AI 听记

列出我的听记

自然语言提示：

我最近创建了哪些 AI 听记？

调用工具： dingtalk_minutes_list_mine

{
  "count": 10
}

获取会议摘要

自然语言提示：

帮我总结一下上午那个需求评审会的内容

调用工具： dingtalk_minutes_get_summary

{
  "minutes_id": "min_xxxxxxxx"
}

提取会议待办

自然语言提示：

从昨天的全员会听记里提取出所有待办事项

调用工具： dingtalk_minutes_get_todos

{
  "minutes_id": "min_xxxxxxxx"
}

获取完整转写文本

自然语言提示：

给我看一下"技术评审"会议的完整文字记录

调用工具： dingtalk_minutes_get_transcription

{
  "minutes_id": "min_xxxxxxxx"
}

邮箱

搜索邮件

自然语言提示：

帮我找所有来自 boss@company.com 关于"Q3 预算"的邮件

调用工具： dingtalk_mail_message_list

{
  "query": "from:boss@company.com subject:Q3预算",
  "count": 10
}

发送邮件

自然语言提示：

给 hr@company.com 发一封邮件，主题"请假申请"，内容是申请明天请年假一天

调用工具： dingtalk_mail_message_send

{
  "to": "hr@company.com",
  "subject": "请假申请",
  "body": "您好，\n\n本人申请 2026年6月18日（明天）请年假一天，请审批。\n\n谢谢！",
  "cc": "manager@company.com"
}

在线电子表格

读取表格数据

自然语言提示：

读取"销售数据.axls"Sheet1 的 A1:D20 区域

调用工具： dingtalk_sheet_read

{
  "sheet_id": "sheet_xxxxxxxx",
  "range": "Sheet1!A1:D20"
}

写入表格数据

自然语言提示：

在"周报汇总表"的 B2 单元格写入今天的数据

调用工具： dingtalk_sheet_update

{
  "sheet_id": "sheet_xxxxxxxx",
  "range": "Sheet1!B2",
  "values": "[[\"完成\",\"85%\",\"正常\"]]"
}

追加数据到表格

自然语言提示：

在"出勤记录表"末尾追加今天的打卡数据

调用工具： dingtalk_sheet_append

{
  "sheet_id": "sheet_xxxxxxxx",
  "range": "Sheet1",
  "values": "[[\"2026-06-17\",\"张三\",\"09:02\",\"18:05\",\"正常\"]]"
}

知识库

列出知识库空间

自然语言提示：

我有哪些知识库？

调用工具： dingtalk_wiki_space_list

{}

搜索知识库

自然语言提示：

帮我找名字包含"研发"的知识库

调用工具： dingtalk_wiki_space_search

{
  "keyword": "研发"
}

浏览知识库节点

自然语言提示：

列出"研发知识库"里有哪些文档

调用工具： dingtalk_wiki_node_list

{
  "space_id": "space_xxxxxxxx"
}

开发者文档 & 错误诊断

搜索开放平台文档

自然语言提示：

帮我查一下钉钉发送群消息 API 的文档

调用工具： dingtalk_devdoc_article_search

{
  "keyword": "发送群消息"
}

错误诊断

自然语言提示：

我调用接口报错了，requestId 是 abc123，错误码 40013，帮我排查一下

调用工具： dingtalk_devdoc_error_diagnose

{
  "request_id": "abc123",
  "error_code": "40013",
  "message": "无权限访问"
}

AI 搜问

多维人员搜索

自然语言提示：

帮我找负责前端开发、在北京的同事

调用工具： dingtalk_aisearch_person

{
  "query": "负责前端开发、在北京的同事"
}

自然语言提示：

找一下市场部王总的下属有哪些人

调用工具： dingtalk_aisearch_person

{
  "query": "市场部王总的下属"
}

Schema 自省

自然语言提示：

dws 支持哪些产品和功能？

调用工具： dingtalk_schema_discover

{}

常见组合工作流

工作流 1：晨会前准备

目标：上班前用 AI 一键汇总今天的待办、日程和未读消息

1. dingtalk_todo_task_list — 列出所有未完成待办

2. dingtalk_calendar_event_list — 查看今天的日程

3. dingtalk_chat_message_list_unread — 查看未读消息

4. dingtalk_chat_message_list_mentions — 查看 @我 的消息

工作流 2：安排一次团队会议

目标：找到所有人都有空的时间，创建日程并在群里通知

1. dingtalk_contact_dept_list_members — 获取部门成员列表

2. dingtalk_calendar_event_suggest — 推荐所有人都有空的时间段

3. dingtalk_calendar_event_create — 创建日程并邀请所有人

4. dingtalk_chat_search — 找到部门群

5. dingtalk_chat_send_message — 在群里发通知

工作流 3：处理一批审批

目标：批量查看并处理待审批的任务

1. dingtalk_oa_approval_list_pending — 获取所有待审批

2. dingtalk_oa_approval_detail — 查看每条审批单详情

3. dingtalk_oa_approval_tasks — 获取任务 ID

4. dingtalk_oa_approval_approve / dingtalk_oa_approval_reject — 逐一审批

工作流 4：从会议到待办

目标：从 AI 听记中提取待办，自动创建为钉钉任务

1. dingtalk_minutes_list_mine — 找到最近的会议听记

2. dingtalk_minutes_get_todos — 提取会议中的待办事项

3. dingtalk_contact_user_search — 查找负责人的 userId

4. dingtalk_todo_task_create — 逐一创建待办并指派给相应同事

工作流 5：部门消息广播

目标：向某个部门的每位成员发送定制化消息

1. dingtalk_contact_dept_search — 找到目标部门 ID

2. dingtalk_contact_dept_list_members — 获取部门成员

3. dingtalk_chat_send_message — 逐一发送消息（或用 DING 保证必达）

工作流 6：每日自动日报

目标：AI 汇总当天工作内容，自动提交日报

1. dingtalk_todo_task_list — 获取今天完成的待办

2. dingtalk_calendar_event_list — 获取今天参加的会议

3. dingtalk_report_template_detail — 查看日报模板字段

4. dingtalk_report_create — 组装内容提交日报

工作流 7：记录 Bug 并通知负责人

目标：将 Bug 录入 AI 表格并通知负责人

1. dingtalk_aitable_base_search — 找到 Bug 跟踪表

2. dingtalk_aitable_record_create — 创建 Bug 记录

3. dingtalk_contact_user_search — 找到负责人 userId

4. dingtalk_chat_send_message — 发消息通知负责人

参数说明速查

所有 ID 均可通过对应的列表/搜索工具先行查询获取。

许可证

遵循 Apache-2.0 协议。