DingTalk Department Management MCP Server

一个专门用于钉钉部门管理的 Model Context Protocol (MCP) 服务器，为AI助手提供完整的企业部门查询和管理功能。

✨ 功能特性

🏢 核心部门管理功能

• 部门详情查询 - 获取指定部门的完整信息（名称、管理员、权限设置等）
• 部门搜索 - 根据部门名称或拼音快速搜索部门ID
• 子部门管理 - 获取部门的下级子部门列表和ID
• 部门层级 - 查询部门的完整父级路径
• 用户部门关系 - 获取用户所属的所有部门层级

🔐 智能认证机制

• ✅ 支持 App ID + Secret 自动获取token
• ✅ 支持直接使用 Access Token
• ✅ 自动token刷新和本地缓存
• ✅ 错误处理和重试机制

🚀 技术特点

• TypeScript - 完整类型安全支持
• 模块化架构 - 基于成熟的MCP框架
• YAML配置 - 灵活的API配置管理
• 缓存优化 - 减少API调用频率

📦 安装

环境要求

• Node.js 18.0.0 或更高版本
• npm 或 yarn 包管理器

从源码安装

# 克隆项目
git clone https://github.com/your-org/dingtalk-department-mcp.git
cd dingtalk-department-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 全局安装
npm install -g .

从npm安装（发布后）

npm install -g dingtalk-department-mcp

⚙️ 配置

1. 环境变量配置

复制环境变量模板：

cp env.example .env

编辑 .env 文件：

# 推荐方式：使用App ID和Secret
DINGTALK_Client_ID=your_app_id_here
DINGTALK_Client_Secret=your_app_secret_here

# 或者直接使用Access Token
# DINGTALK_ACCESS_TOKEN=your_access_token_here

2. 获取钉钉应用凭证

1. 访问 钉钉开发者后台
2. 创建或选择你的应用
3. 在应用详情中找到 App ID (AppKey) 和 App Secret
4. 确保应用拥有 "通讯录部门信息读权限"

3. Cursor IDE 配置

在 Cursor 的设置中添加 MCP 服务器：

{
  "mcpServers": {
    "dingtalk-department": {
      "command": "dingtalk-department-mcp",
      "env": {
        "DINGTALK_Client_ID": "your_app_id_here",
        "DINGTALK_Client_Secret": "your_app_secret_here"
      }
    }
  }
}

🛠️ 可用工具

1. getDepartmentDetail

获取指定部门的详细信息

// 参数
{
  dept_id: number;      // 部门ID，根部门ID为1
  language?: string;    // 语言设置，zh_CN或en_US
}

2. searchDepartment

根据部门名称搜索部门ID

// 参数
{
  queryWord: string;    // 部门名称或拼音
  offset?: number;      // 分页页码，默认0
  size?: number;        // 分页大小，默认10
}

3. listSubDepartments

获取指定部门的下级子部门列表

// 参数
{
  dept_id?: number;     // 父部门ID，不传则获取根部门
  language?: string;    // 语言设置
}

4. listSubDepartmentIds

获取指定部门的直属子部门ID列表

// 参数
{
  dept_id: number;      // 父部门ID，根部门传1
}

5. getDepartmentParents

获取指定部门的所有父部门路径

// 参数
{
  dept_id: number;      // 要查询的部门ID
}

6. getUserDepartmentParents

获取用户所属的所有部门层级

// 参数
{
  userid: string;       // 用户的userid
}

💡 使用示例

在AI助手中使用

用户: 帮我查找财务部门的详细信息
AI: 我来帮你搜索财务部门并获取详细信息...

用户: 列出市场部的所有子部门
AI: 我来获取市场部的子部门列表...

用户: 查看张三所属的所有部门层级
AI: 我来查询张三的部门归属情况...

直接命令行使用

# 启动服务器
dingtalk-department-mcp

# 开发模式
npm run dev

🏗️ 开发

项目结构

dingtalk-department-mcp/
├── src/
│   ├── index.ts              # 主服务器类
│   ├── cli.ts                # 命令行入口
│   └── types.ts              # 类型定义
├── dingtalk_department_mcp.yaml  # API配置
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript配置
├── env.example               # 环境变量模板
└── README.md                 # 说明文档

开发命令

# 安装依赖
npm install

# 开发模式（自动重新构建）
npm run dev

# 构建项目
npm run build

# 类型检查
npm run type-check

# 清理构建产物
npm run clean

# 测试
npm test

添加新的API

1. 在 dingtalk_department_mcp.yaml 中添加新的工具配置
2. 更新 src/types.ts 中的类型定义
3. 如需特殊处理，修改 src/index.ts 中的相关方法
4. 重新构建项目

📚 API 文档

本项目支持的钉钉API：

| API | 版本 | 端点 | 说明 | |-----|------|------|------| | 获取部门详情 | v2 | /topapi/v2/department/get | 获取完整部门信息 | | 搜索部门 | v1.0 | /v1.0/contact/departments/search | 按名称搜索部门 | | 获取子部门列表 | v2 | /topapi/v2/department/listsub | 获取下级部门 | | 获取子部门ID | v2 | /topapi/v2/department/listsubid | 获取子部门ID | | 获取部门父级 | v2 | /topapi/v2/department/listparentbydept | 获取父部门路径 | | 获取用户部门 | v2 | /topapi/v2/department/listparentbyuser | 获取用户部门路径 |

🔧 故障排除

常见问题

1. Token认证失败

   • 检查App ID和Secret是否正确
   • 确认应用拥有必要的权限
   • 查看token缓存文件是否损坏

2. API调用失败

   • 检查网络连接
   • 确认API端点是否正确
   • 查看钉钉API文档获取最新信息

3. 构建错误

   • 确保Node.js版本 >= 18.0.0
   • 删除 node_modules 重新安装依赖
   • 检查TypeScript版本兼容性

调试模式

设置环境变量启用详细日志：

DEBUG=dingtalk-department:* npm run dev

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

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

🔗 相关链接

• 钉钉开放平台
• Model Context Protocol
• Cursor IDE
• TypeScript

📞 支持

如果你遇到问题或有建议，请：

1. 查看 Issues
2. 创建新的 Issue
3. 联系维护者

Made with ❤️ for the DingTalk developer community