🎯 DingTalk ServiceWindow MCP Server

一个功能强大的钉钉服务窗 MCP 服务器，专为 AI 助手提供完整的服务窗管理能力。

📥 安装

# 全局安装
npm install -g dingtalk-servicewindow-mcp

# 或使用 NPX 直接运行
npx dingtalk-servicewindow-mcp

✨ 核心特性

🌟 智能消息构建器

• 🛠️ 简化复杂格式：将复杂的服务窗消息格式简化为用户友好的参数
• 🔧 类型安全：TypeScript 全覆盖，避免参数错误
• ✅ 智能验证：内置参数验证，支持长度限制、格式检查
• 📝 4种消息类型：文本、链接、Markdown、卡片消息

📡 完整功能覆盖

• 📤 消息发送：单人消息、批量消息
• 👥 用户管理：获取粉丝信息、查询关注状态
• 🏢 服务窗管理：获取企业服务窗列表
• 🔄 智能Token管理：自动刷新、本地缓存

🚀 快速开始

📦 方式1：NPM安装（推荐）

# 全局安装
npm install -g dingtalk-servicewindow-mcp

# 设置环境变量
export DINGTALK_Client_ID=your_app_key
export DINGTALK_Client_Secret=your_app_secret

# 运行服务器
dingtalk-servicewindow-mcp

🎯 方式2：NPX直接运行

# 设置环境变量
export DINGTALK_Client_ID=your_app_key
export DINGTALK_Client_Secret=your_app_secret

# 运行服务器
npx dingtalk-servicewindow-mcp

🔧 方式3：本地开发

# 克隆项目
git clone <repository-url>
cd dingtalk-servicewindow-mcp

# 安装依赖
npm install

# 配置环境变量
cp env.example .env
# 编辑 .env 文件，填入你的钉钉应用信息

# 启动服务器
npm start

⚙️ 配置说明

🔑 环境变量

| 变量名 | 必填 | 描述 | |--------|------|------| | DINGTALK_Client_ID | ✅ | 钉钉应用的AppKey | | DINGTALK_Client_Secret | ✅ | 钉钉应用的AppSecret | | DINGTALK_ACCESS_TOKEN | ⭕ | 直接使用AccessToken（测试用） | | DINGTALK_ACCOUNT_ID | ⭕ | 服务窗账号ID（非自建应用时需要） |

🏢 获取钉钉应用信息

1. 访问 钉钉开发者后台
2. 创建企业内部应用或服务窗应用
3. 获取 AppKey 和 AppSecret
4. 配置应用权限（服务窗相关权限）

🛠️ MCP 工具列表

1️⃣ buildServiceWindowMessage 🌟核心特色

构建标准化的服务窗消息体，支持4种消息类型：

📝 文本消息

{
  "messageType": "text",
  "content": "这是一条文本消息"
}

�� 链接消息

{
  "messageType": "link",
  "title": "消息标题",
  "text": "消息描述",
  "messageUrl": "https://example.com",
  "picUrl": "@media123"
}

📄 Markdown消息

{
  "messageType": "markdown",
  "title": "Markdown消息",
  "text": "支持**粗体**和*斜体*等格式"
}

🎴 卡片消息

// 整体跳转卡片
{
  "messageType": "actionCard",
  "cardType": "single",
  "title": "卡片标题",
  "markdown": "卡片内容支持**Markdown**",
  "singleTitle": "查看详情",
  "singleUrl": "https://example.com"
}

// 独立跳转卡片
{
  "messageType": "actionCard",
  "cardType": "independent",
  "title": "选择操作",
  "markdown": "请选择要执行的操作",
  "orientation": "vertical",
  "buttons": [
    {"title": "确认", "url": "https://example.com/confirm"},
    {"title": "取消", "url": "https://example.com/cancel"}
  ]
}

2️⃣ sendServiceWindowMessage

发送服务窗单人消息

{
  "userId": "user123", 
  "messageBody": {/* 使用buildServiceWindowMessage构建 */}
}

3️⃣ batchSendServiceWindowMessage

批量发送服务窗消息

{
  "userIdList": ["user1", "user2", "user3"],
  "messageBody": {/* 消息体 */}
}

4️⃣ getServiceWindowFollower

获取单个粉丝信息

5️⃣ listServiceWindowFollowers

获取粉丝列表（支持分页）

6️⃣ getUserFollowStatus

查询用户关注状态

7️⃣ listServiceWindows

获取企业服务窗列表

💡 使用示例

场景1：发送营销消息

// 1. 构建卡片消息
const message = await buildServiceWindowMessage({
  messageType: "actionCard",
  cardType: "independent", 
  title: "限时优惠活动",
  markdown: "🎉 **双十一大促**\n\n全场商品5折起！",
  orientation: "horizontal",
  buttons: [
    {"title": "立即抢购", "url": "https://shop.com/sale"},
    {"title": "分享好友", "url": "https://shop.com/share"}
  ]
});

// 2. 批量发送给粉丝
await batchSendServiceWindowMessage({
  sendToAll: true,
  messageBody: message.messageBody
});

场景2：客服自动回复

// 1. 构建文本消息
const reply = await buildServiceWindowMessage({
  messageType: "text",
  content: "感谢您的咨询！我们的客服将在30分钟内回复您。"
});

// 2. 发送给特定用户
await sendServiceWindowMessage({
  userId: "customer123",
  messageBody: reply.messageBody
});

场景3：用户关注管理

// 1. 获取粉丝列表
const followers = await listServiceWindowFollowers({
  maxResults: 50
});

// 2. 检查特定用户关注状态
const status = await getUserFollowStatus({
  userId: "user123"
});

// 3. 获取用户详细信息
const userInfo = await getServiceWindowFollower({
  userId: "user123"
});

🎯 在 Claude Desktop 中配置

方式1：使用全局安装的包

{
  "mcpServers": {
    "dingtalk-servicewindow": {
      "command": "dingtalk-servicewindow-mcp",
      "env": {
        "DINGTALK_Client_ID": "your_app_key",
        "DINGTALK_Client_Secret": "your_app_secret"
      }
    }
  }
}

方式2：使用NPX（无需安装）

{
  "mcpServers": {
    "dingtalk-servicewindow": {
      "command": "npx",
      "args": ["dingtalk-servicewindow-mcp"],
      "env": {
        "DINGTALK_Client_ID": "your_app_key",
        "DINGTALK_Client_Secret": "your_app_secret"
      }
    }
  }
}

🔧 高级配置

🎨 消息验证规则

消息构建器内置了完整的验证规则：

• 文本消息：1-500字符
• 链接标题：1-128字符
• Markdown标题：1-30字符
• 卡片内容：1-1000字符
• 按钮标题：1-20字符
• URL格式：必须以http://或https://开头

🔒 权限要求

应用需要以下权限：

• 服务窗发送消息权限
• 服务窗联系人信息读权限
• 服务窗帐号信息读取权限

📊 API限制

• 单人消息：每天累计调用次数 ≤ 粉丝数量
• 批量消息：每天最多100次
• 每个粉丝每天最多收到3条消息
• 相同内容消息会去重

🔍 故障排除

常见问题

1. Token认证失败

   • 检查AppKey/Secret是否正确
   • 确认应用权限是否充足

2. 消息发送失败

   • 验证用户ID是否有效
   • 检查消息格式是否正确

3. 网络连接问题

   • 确认网络连接正常
   • 检查防火墙设置

调试模式

# 设置调试环境变量
export DEBUG=dingtalk:*
npm start

🤝 贡献指南

1. Fork 项目
2. 创建功能分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 创建 Pull Request

📝 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• NPM包地址
• 钉钉开放平台
• 服务窗开发文档
• Model Context Protocol
• Cursor IDE

🌟 如果这个项目对你有帮助，请给一个 Star！

Made with ❤️ by DingTalk MCP Team