钉钉工作通知 MCP 服务器

🔔 专门用于钉钉企业内部应用的工作通知功能的 Model Context Protocol (MCP) 服务器。

✨ 功能特性

📱 支持的消息类型

• markdown - Markdown消息：支持富文本格式，包含标题、文本、链接、列表等

🛠️ 支持的操作

1. sendNotice - 发送工作通知
2. getSendResult - 获取发送结果
3. getSendProgress - 获取发送进度
4. recallNotice - 撤回工作通知

🚀 快速开始

1. 安装包

npm install dingtalk-notice-mcp

2. 环境准备

# 进入项目目录
cd node_modules/dingtalk-notice-mcp

# 或者如果你想全局安装
npm install -g dingtalk-notice-mcp

3. 配置环境变量

创建 .env 文件，填入你的钉钉应用信息：

# 必需配置
DINGTALK_CLIENT_ID=your_client_id_here
DINGTALK_CLIENT_SECRET=your_client_secret_here  
DINGTALK_AGENT_ID=your_agent_id_here

# 可选配置（优先级更高）
DINGTALK_ACCESS_TOKEN=your_access_token_here

4. 获取配置信息

1. 登录 钉钉开发者后台
2. 进入你的企业内部应用
3. 在"应用信息"页面获取：
   • Client ID (AppKey)
   • Client Secret (AppSecret)
   • Agent ID (应用的AgentId)

5. 启动服务器

node dingtalk-notice-mcp-server.js

📖 使用指南

发送 Markdown 消息

基础 Markdown 消息

{
  "name": "sendNotice",
  "arguments": {
    "userid_list": "user001,user002",
    "msg": {
      "msgtype": "markdown",
      "markdown": {
        "title": "会议提醒",
        "text": "# 会议提醒\\n\\n请大家准时参加明天上午10点的工作会议。"
      }
    }
  }
}

富文本 Markdown 消息

{
  "name": "sendNotice", 
  "arguments": {
    "userid_list": "user001",
    "msg": {
      "msgtype": "markdown",
      "markdown": {
        "title": "重要通知",
        "text": "# 重要通知\\n\\n请大家注意：\\n\\n- **会议时间**: 明天上午10:00\\n- **会议地点**: 会议室A\\n- **参会人员**: 全体员工\\n\\n## 会议议程\\n\\n1. 项目进度汇报\\n2. 下阶段工作安排\\n3. 问题讨论\\n\\n---\\n\\n**请务必准时参加！**"
      }
    }
  }
}

包含链接的 Markdown 消息

{
  "name": "sendNotice",
  "arguments": {
    "userid_list": "user001",
    "msg": {
      "msgtype": "markdown",
      "markdown": {
        "title": "项目文档更新",
        "text": "## 项目文档已更新\\n\\n最新的项目文档已上传，请查看：\\n\\n[点击查看项目文档](https://www.example.com/project-docs)\\n\\n### 更新内容\\n\\n- 新增API接口说明\\n- 更新部署指南\\n- 添加故障排除章节"
      }
    }
  }
}

查询发送结果

{
  "name": "getSendResult",
  "arguments": {
    "task_id": "123456789"
  }
}

查询发送进度

{
  "name": "getSendProgress",
  "arguments": {
    "task_id": "123456789"
  }
}

撤回消息

{
  "name": "recallNotice",
  "arguments": {
    "msg_task_id": "123456789"
  }
}

📊 API限制

企业内部应用限制

• 发送对象: 最多5000人/次
• 发送频率: 每天每员工最多500条
• 消息类型: 支持 markdown 消息类型

应用类型支持

• ✅ 企业内部应用 - 完全支持
• ❌ 第三方企业应用 - 不支持
• ❌ 个人应用 - 不支持

⚠️ 注意事项

1. 应用类型限制

• 仅支持企业内部应用，不支持第三方企业应用
• 已完全移除第三方应用相关代码，避免混淆

2. 消息类型限制

• 仅支持 markdown 消息类型：专注于富文本格式
• 不支持媒体文件类型（image、voice、file、action_card）
• 不支持OA消息类型

3. Token管理

• 自动Token管理：支持自动获取和缓存Access Token
• Token缓存时间：7200秒（提前10分钟过期）
• 支持直接配置Access Token（优先级更高）

4. 权限要求

• 需要开通"工作通知"权限
• 需要获取员工手机号权限（用于发送）

🔧 故障排除

常见错误

1. 认证失败

错误信息：Failed to get access token 或 认证失败

解决方案：

• 检查Client ID/Secret是否正确
• 确认Agent ID是否匹配
• 验证应用权限是否足够
• 确认应用类型是否为企业内部应用

2. 发送失败

错误信息：发送失败 或参数错误

解决方案：

• 确认接收人用户ID格式正确（用逗号分隔）
• 检查消息格式是否符合规范
• 验证是否超出发送限制（5000人/次，500条/天/人）
• 参考文档中的 markdown 消息示例格式

3. 消息格式错误

错误信息：不支持的消息类型 或字段缺失

解决方案：

• 确保使用 markdown 消息类型
• 检查必需字段是否完整（title、text）
• 参考文档中的示例格式
• 验证 markdown 语法是否正确

调试技巧

1. 参考示例格式：使用文档中提供的 markdown 消息示例
2. 分步测试：先发送简单的 markdown 消息测试连通性
3. 查看详细错误：所有API都返回详细的错误信息
4. 检查环境变量：确认所有必需的环境变量都已正确配置

📚 相关资源

官方文档

• 钉钉开发者平台
• 工作通知API文档
• Model Context Protocol

API参考

• 发送工作通知
• 获取发送结果

开发资源

• Node.js官方文档
• axios HTTP客户端
• MCP SDK文档

📝 更新日志

v2.0.0 (2024-12-25) - 当前版本

• 🎯 简化设计：专注于 markdown 消息类型
• ❌ 移除功能：删除 text 和 link 消息类型支持
• ❌ 移除工具：删除 getMessageTemplates 工具
• ✨ 优化体验：更简洁的API，减少用户选择困扰
• 📦 包优化：减少包体积，提升性能
• 📚 文档更新：完整的 markdown 消息示例和最佳实践
• 🔧 向前聚焦：专注于最强大灵活的消息格式

v1.1.0 (2024-12-25)

• 🔄 完整 TypeScript 重构: 从 JavaScript 迁移到完整的 TypeScript 实现
• 🎯 ESM 模块优化: 原生 ES 模块支持，更好的现代化兼容性
• 🛡️ 自动 Token 管理: 智能缓存和自动刷新机制
• 📚 完善的类型定义: 100% TypeScript 类型覆盖

v1.0.0 (2024-12-19)

• 🎉 首个npm发布版本
• ✅ 支持3种核心消息类型（text、link、markdown）
• ✅ 支持5个核心API操作（发送、查询结果、查询进度、撤回、模板）
• ✅ 企业内部应用专用实现
• ✅ 自动Token管理和缓存
• ✅ 内置消息模板功能
• ✅ 完善的错误处理机制
• 📦 可通过npm直接安装使用

特性亮点

• 🎯 专门优化：完全针对企业内部应用优化
• 🚫 简化设计：移除复杂的OA消息和第三方应用支持
• 🔧 自动化：提供完整的自动化构建和部署流程
• 📚 文档完善：包含详细的使用说明和示例
• 🛡️ 安全可靠：具备完善的错误处理和安全机制

📄 许可证

MIT License

Copyright (c) 2024 DingTalk Notice MCP Generator

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🚀 立即开始使用

现在你可以立即开始使用这个钉钉工作通知MCP服务器了！

1. 配置环境变量 - 填入你的钉钉应用信息
2. 安装依赖 - 运行 npm install
3. 启动服务器 - 运行 node dingtalk-notice-mcp-server.js
4. 发送第一条消息 - 使用 sendNotice 工具

如果遇到任何问题，请参考故障排除部分或查看相关资源链接。