Content
# DingTalk Robot MCP
DingTalk Robot MCP Server. Achieve AI assistant to send DingTalk single chat and group chat messages through MCP protocol, supporting **text, Markdown, image, link, ActionCard, file, audio, video** for 8 message types. Messages can be sent by **userId**, **name**, or **batch userId**, with a maximum of 20 people per batch.
[](https://opensource.org/licenses/MIT)
---
## Features
| Feature | Description |
|---|---|
| Multiple Message Types | text, Markdown, image, link, ActionCard, file, audio, video |
| Single Chat Messages | Send various types of messages to specified users |
| Group Chat Messages | Send various types of messages to specified groups |
| Media Upload | Upload local files to obtain mediaId for image/file/audio/video messages |
| Send by userId | Directly specify DingTalk user ID (compatible with old usage) |
| Send by Name | Input Chinese name, automatically search for userId and send |
| Batch Sending | Send to up to 20 users at once |
| Duplicate Name Detection | Reject sending when multiple users have the same name, list all duplicate userIds |
---
## Prerequisites
| Project | Requirements |
|---|---|
| Node.js | >= 18.0.0 |
| DingTalk Application | Internal Enterprise Application (Robot) |
---
## Step 1: Create DingTalk Application
1. Log in to [DingTalk Open Platform](https://open.dingtalk.com/), go to "Application Development" → "Internal Enterprise Application"
2. Create an application, select **「Robot」** as the type
3. On the "Credentials and Basic Information" page, obtain:
- **AppKey** (unique identifier of the application)
- **AppSecret** (application's secret key)
---
## Step 2: Enable DingTalk Permissions
### Basic Permissions (required)
Ensure the application has enabled **「Enterprise Robot Message Push」** permission. This is the basic permission for sending messages, usually enabled by default when creating a robot application.
Verification method: On the application details page → "Permission Management" → confirm the existence of "Enterprise Robot Message Push".
### Send by Name Permission (optional)
If you want to send messages by Chinese name (not required, only `userId` sending is not needed), you also need to enable:
| Permission Name | Description | Operation Path |
|---|---|---|
| Contact Department Information Read Permission | Get enterprise department list | Permission Management → search "Contact" → click to enable |
| Contact Member Information Read Permission | Get department member information | Permission Management → search "Contact" → click to enable |
> **Note**: The "Permission Management" entrance is on the left menu of the DingTalk open platform application details page, and different version background interfaces may be slightly different. If you can't find it, try "Development Management" → "Permission Management".
---
## Step 3: Installation & Configuration
### Global Installation via npm (recommended)
```bash
npm install -g dingtalk-mcp-server
```
After installation, run the configuration wizard:
```bash
dingtalk-mcp-server-config
```
The wizard will guide you to input AppKey and AppSecret and automatically write them into WorkBuddy configuration.
### Manual Configuration
Edit `~/.workbuddy/mcp.json`:
```json
{
"mcpServers": {
"dingtalk": {
"command": "node",
"args": [
"C:\\path\\to\\dingtalk-mcp-server\\dist\\index.js"
],
"env": {
"DINGTALK_APP_KEY": "your AppKey",
"DINGTALK_APP_SECRET": "your AppSecret"
}
}
}
}
```
| Environment Variable | Required | Description |
|---|---|---|
| `DINGTALK_APP_KEY` | ✅ | DingTalk application AppKey |
| `DINGTALK_APP_SECRET` | ✅ | DingTalk application AppSecret |
After configuration, disconnect and re-enable the DingTalk connector to take effect.
---
## User Guide
### MCP Tool List
| Tool Name | Function |
|---|---|
| `send_dingtalk_single_message` | Send single chat messages (support 8 message types) |
| `send_dingtalk_group_message` | Send group chat messages (support 8 message types) |
| `upload_dingtalk_media` | Upload media files, obtain mediaId |
### Single Chat Message Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `msgtype` | string | No (default text) | Message type: text / markdown / image / link / actionCard_single / actionCard_multi / file / audio / video |
| `userId` | string | One of three | Single user ID |
| `userIds` | string[] | One of three | Multiple user IDs (up to 20) |
| `userName` | string | One of three | User's Chinese name (exact match) |
**Additional parameters for each message type:**
| msgtype | Additional Required Parameters | Optional Parameters |
|---|---|---|
| text | `content` (text content) | — |
| markdown | `title` (title), `text` (Markdown text) | — |
| image | `photoURL` (image URL or mediaId) | — |
| link | `title`, `text`, `messageUrl` | `picUrl` (preview image) |
| actionCard_single | `title`, `text`, `singleTitle`, `singleURL` | `btnOrientation` (0 vertical / 1 horizontal) |
| actionCard_multi | `title`, `text`, `btns[]` (button array, 1-6) | `btnOrientation` |
| file | `mediaId`, `fileName`, `fileType` | — |
| audio | `mediaId`, `duration` (milliseconds) | — |
| video | `videoMediaId`, `picMediaId`, `duration` (seconds) | `videoType`, `width`, `height` |
### Group Chat Message Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `chatId` | string | ✅ | Group chat openConversationId |
| `msgtype` | string | No (default text) | Message type (same as single chat) |
Other parameters are consistent with single chat messages for each type.
### Upload Media File Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `filePath` | string | ✅ | Local file absolute path |
| `mediaType` | string | ✅ | image / voice / video / file |
| mediaType | Supported Formats | Size Limit |
|---|---|---|
| image | jpg, png, gif, bmp | 20MB |
| voice | amr, mp3, wav | 2MB |
| video | mp4 | 20MB |
| file | doc, docx, xls, xlsx, ppt, pptx, zip, pdf, rar | 20MB |
### Usage Examples
**Example 1: Send Text (backward compatible)**
```
Send a message to Zhang San, userId: "204457105626433998", content: The meeting tomorrow is changed to 3 pm
```
**Example 2: Send by Name**
```
Send a message to Zhu Yumin via DingTalk, content: Please receive this week's test report
```
**Example 3: Send Markdown**
```
Send a markdown message to userId "011950195121139389" via DingTalk, title: Weekly Report Reminder, text: **Please submit your weekly report by Friday**\n\n- Weekly summary\n- Next week's plan
```
**Example 4: Upload and Send Image**
```
Upload D:\screenshot.png to DingTalk (mediaType: image), get mediaId, and send it to Zhu Yumin via DingTalk, msgtype is image
```
**Example 5: Send ActionCard**
```
Send an actionCard to userId "011950195121139389", msgtype: actionCard_single, title: New Version Released, text: ## v2.0 is online\n\nAdd support for multiple message types, singleTitle: View Details, singleURL: https://github.com
```
**Example 6: Batch Sending**
```
Send a message to the following users via DingTalk:
userIds: ["204457105626433998", "481029384729103847"]
msgtype: text, content: Full staff notification: The system will be upgraded and maintained at 3 pm tomorrow
```
---
## Behavior Description
### Name Search Mechanism
- When sending by name for the first time, the MCP server will traverse all departments of the enterprise to build a name → userId index (takes about 5~10 seconds, depending on the enterprise size)
- Index cache for 5 minutes, subsequent searches < 1ms
- Requires **Contact Department Information Read Permission** + **Contact Member Information Read Permission**
### Duplicate Name Handling
```
User "Zhang Wei" has 3 duplicate records in the enterprise
→ Sending failed, error message lists 3 userIds
→ User needs to use userId to specify the recipient
```
### Batch Limitation
A maximum of 20 users can be sent to at once. If more users need to be sent, please call in batches.
---
## Obtain userId / chatId
### Obtain Your Own userId
The most common scenario is to send a message to yourself. In the DingTalk client:
1. Click avatar → Personal Information
2. Long press or click "Copy" your userId (depending on the version)
3. Or **send to yourself by name**
### Obtain Other's userId
1. Use this MCP's **send by name** function to automatically search
2. Or log in to DingTalk management backend → Contact → User details page URL contains userId
### Obtain chatId (Group Chat openConversationId)
1. In DingTalk group settings → Group Robot → View robot details
2. Or obtain through DingTalk Open Platform API
---
## Troubleshooting
### Issue 1: MCP Tool Not Displayed
1. Check if `~/.workbuddy/mcp.json` path is correct
2. Confirm `node` command is available (`node --version`)
3. Disconnect DingTalk connector → Re-enable
### Issue 2: Send by Name Reports "Not Found"
- Confirm "Contact Department Information Read Permission" and "Contact Member Information Read Permission" are enabled
- Disconnect and re-enable DingTalk connector to make permissions take effect
- Confirm name is exactly the same as in DingTalk contact
### Issue 3: Message Sending Failed
- Check AppKey / AppSecret are correct
- Confirm "Enterprise Robot Message Push" permission is enabled
- Confirm userId is valid and the user is within the application's visible range
### Issue 4: Sent Successfully but Recipient Doesn't Receive
- Confirm the user is within the application's visible range
- The application needs to set the visible range to "All Employees" or include the target user in "Deployment and Release"
---
## Tech Stack
- TypeScript
- @modelcontextprotocol/sdk
- axios
- DingTalk Open Platform API (new v1.0)
## API Description
| Operation | API |
|---|---|
| Get Token | `POST /v1.0/oauth2/accessToken` |
| Single Chat Message | `POST /v1.0/robot/oToMessages/batchSend` |
| Group Chat Message | `POST /v1.0/robot/groupMessages/send` |
| Upload Media | `POST /oapi.dingtalk.com/media/upload` |
| Department List | `GET /oapi.dingtalk.com/department/list` |
| Department Members | `GET /oapi.dingtalk.com/user/simplelist` |
## License
MIT
