钉钉签到MCP Server

这是一个基于钉钉签到API的MCP (Model Context Protocol) Server，提供签到记录查询功能，可与AI助手集成。

功能特性

• 📋 部门签到记录 - 获取指定部门的员工签到记录
• 👤 用户签到记录 - 获取指定用户的签到记录
• 🔐 自动认证 - 支持Client ID/Secret自动获取和刷新access_token
• 💾 Token缓存 - 本地缓存access_token，避免频繁刷新
• 🚀 标准化接口 - 基于MCP协议，可与任何支持MCP的AI助手集成

安装

方式一：npm 安装（推荐）

npm install -g dingtalk-checkin-mcp

方式二：从源码安装

git clone https://github.com/your-org/dingtalk-checkin-mcp.git
cd dingtalk-checkin-mcp
npm install

快速开始

1. 获取钉钉应用凭证

1. 登录钉钉开放平台
2. 创建企业内部应用
3. 获取Client ID和Client Secret
4. 配置应用权限：
   • 获取签到数据的权限
   • 通讯录部门信息读权限（可选，如需查询部门信息）

2. 配置环境变量

# 如果从 npm 安装，可以创建配置文件
mkdir -p ~/.config/dingtalk-checkin-mcp
echo "CLIENT_ID=your_client_id" >> ~/.config/dingtalk-checkin-mcp/.env
echo "CLIENT_SECRET=your_client_secret" >> ~/.config/dingtalk-checkin-mcp/.env

# 如果从源码安装
cp env.example .env
# 编辑.env文件，填入你的应用凭证
vim .env

3. 启动服务

# 如果从 npm 安装
dingtalk-checkin-mcp

# 如果从源码安装
# 加载环境变量
source .env
# 启动MCP Server
node mcp-server.js

可用的API工具

1. getDepartmentCheckinRecords

获取部门用户签到记录，以部门维度获取员工签到记录进行统计分析。

参数：

• department_id (必填) - 部门ID，1表示根部门
• start_time (必填) - 开始时间，Unix时间戳（毫秒）
• end_time (必填) - 结束时间，Unix时间戳（毫秒）
• offset (可选) - 分页偏移量，默认0
• size (可选) - 分页大小，最大100，默认100
• order (可选) - 排序方式，asc/desc，默认asc

使用示例：

{
  "department_id": "1",
  "start_time": 1704067200000,  // 2024-01-01 00:00:00
  "end_time": 1704153600000,    // 2024-01-02 00:00:00
  "offset": 0,
  "size": 50,
  "order": "asc"
}

2. getUserCheckinRecords

获取指定用户的签到记录，可获取指定人员的签到记录进行统计分析。

参数：

• userid_list (必填) - 用户ID列表，多个用逗号分隔，最多10个
• start_time (必填) - 开始时间，Unix时间戳（毫秒）
• end_time (必填) - 结束时间，Unix时间戳（毫秒）
• cursor (必填) - 分页游标，开始时传0
• size (必填) - 分页大小，最大100

使用示例：

{
  "userid_list": "manager4220",
  "start_time": 1704067200000,  // 2024-01-01 00:00:00
  "end_time": 1704153600000,    // 2024-01-02 00:00:00
  "cursor": 0,
  "size": 100
}

返回数据格式

部门签到记录返回格式

{
  "errcode": 0,
  "data": [
    {
      "name": "张三",
      "userId": "manager4220",
      "avatar": "https://static.dingtalk.com/media/xxxx",
      "timestamp": 1599544940000,
      "place": "绿城未来park",
      "detailPlace": "杭州市五常街道",
      "remark": "拜访客户",
      "imageList": ["https://static.dingtalk.com/media/xxxx"],
      "latitude": "30.286053",
      "longitude": "120.017394"
    }
  ],
  "errmsg": "ok"
}

用户签到记录返回格式

{
  "errcode": 0,
  "result": {
    "page_list": [
      {
        "checkin_time": 1599544940000,
        "detail_place": "浙江省杭州市余杭区五常街道",
        "image_list": ["https://static.dingtalk.com/media/xxxx"],
        "place": "绿城未来park",
        "remark": "客户拜访",
        "userid": "manager4220",
        "longitude": "120.017394",
        "latitude": "30.286046",
        "visit_user": "刘先生"
      }
    ],
    "next_cursor": 100
  },
  "request_id": "pod643x3uywf"
}

在AI助手中使用

Cursor IDE

1. 确保MCP Server正在运行
2. 在Cursor中配置MCP服务器连接
3. 使用自然语言询问签到相关问题：
   • "帮我查询技术部门昨天的签到记录"
   • "获取张三这周的签到统计"
   • "分析销售部门本月的签到情况"

其他MCP兼容工具

任何支持MCP协议的AI工具都可以使用此服务器，包括但不限于：

• Claude Desktop
• VS Code extensions
• 自定义AI应用

故障排除

1. 认证失败

• 检查Client ID和Client Secret是否正确
• 确认应用已获得"获取签到数据的权限"
• 检查应用类型是否为企业内部应用

2. API调用失败

• 检查参数格式是否正确
• 确认时间范围不超过限制（部门记录45天，用户记录1-10天）
• 查看错误信息中的errcode和errmsg

3. 服务启动失败

• 确认Node.js版本 >= 18.0.0
• 检查所有依赖是否正确安装
• 查看启动日志获取详细错误信息

开发

项目结构

dingtalk-checkin-mcp/
├── package.json                 # 项目配置
├── mcp-server.js               # MCP服务器主文件
├── dingtalk_mcp_server.yaml    # API工具配置
├── env.example                 # 环境变量示例
├── README.md                   # 项目文档
└── .dingtalk_token_cache.json  # Token缓存文件（自动生成）

修改和扩展

如需添加更多API功能：

1. 在dingtalk_mcp_server.yaml中添加新的工具配置
2. 确保mcp-server.js能正确解析新的配置
3. 测试新功能是否正常工作

许可证

本项目基于MIT许可证开源。

相关链接

• 钉钉开放平台
• MCP协议规范
• 签到记录API文档