🚀 🔔 Claude Code DingTalk MCP Server

An MCP Server implementation that integrates Claude Code with DingTalk robot notifications.

✨ Features

• ✅ Environment Variable Configuration - Supports automatic initialization via environment variables, eliminating the need for manual configuration.
• ✅ DingTalk Group Robot Integration - Full support for the Webhook API.
• ✅ Multiple Message Formats - Supports three message types: text, Markdown, and links.
• ✅ Secure Signature Verification - Supports HMAC-SHA256 signature verification.
• ✅ Dedicated Task Notifications - Formatted templates for task completion notifications.
• ✅ Developed in TypeScript - Offers full type safety and intelligent code suggestions.
• ✅ Plug-and-Play - Seamlessly integrates with Claude Code.

🚀 Quick Start in 5 Minutes

Step 1: Installation

npm install -g claude-code-dingtalk-mcp

Install using the Claude MCP Manager (Recommended)

claude mcp add dingtalk-mcp dingtalk-mcp-server

Step 2: Obtain DingTalk Robot Information

1. Go to the DingTalk group → Group settings → Intelligent group assistant → Add robot → Custom.
2. Select "Signing" for security settings and obtain the Webhook URL and secret key.

Step 3: Configure Environment Variables

export DINGTALK_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"
export DINGTALK_SECRET="YOUR_SECRET"

Step 4: Configure Claude Code

Create a .mcp.json file:

{"mcpServers": {"dingtalk-notifications": {"command": "dingtalk-mcp-server"}}}

Step 5: Testing

Restart Claude Code and then run:

dingtalk_send_text {"content": "Test successful!"}

✅ Done! Now you can call dingtalk_notify_session_end to send notifications at the end of each conversation.

Method 1: npm Installation (Recommended)

npm install -g claude-code-dingtalk-mcp

Method 2: Installation via MCP Manager

# If your Claude Code supports the MCP Manager
npx @modelcontextprotocol/cli add claude-code-dingtalk-mcp

Method 3: Direct Use with npx

# Use directly without installation
npx claude-code-dingtalk-mcp

📦 Installation Guide

Step 1: Install the DingTalk MCP Server

Choose one of the following installation methods:

# Method 1: Global installation (Recommended)
npm install -g claude-code-dingtalk-mcp

# Method 2: Local installation in the project
npm install claude-code-dingtalk-mcp

# Method 3: Direct use (no installation required)
npx claude-code-dingtalk-mcp

Step 2: Configure Claude Code

Create/edit the .mcp.json file in your project root directory or the global configuration directory of Claude Code:

Global installation method:

{
  "mcpServers": {
    "dingtalk-notifications": {
      "command": "dingtalk-mcp-server",
      "description": "DingTalk notification server"
    }
  }
}

Local installation method:

{
  "mcpServers": {
    "dingtalk-notifications": {
      "command": "node",
      "args": ["./node_modules/claude-code-dingtalk-mcp/dist/index.js"],
      "description": "DingTalk notification server"
    }
  }
}

NPX method:

{
  "mcpServers": {
    "dingtalk-notifications": {
      "command": "npx", 
      "args": ["claude-code-dingtalk-mcp"],
      "description": "DingTalk notification server"
    }
  }
}

Step 3: Configure the DingTalk Robot

3.1 Create a DingTalk Group Robot

1. In the DingTalk group: Group settings → Intelligent group assistant → Add robot.
2. Select the "Custom" robot.
3. Set the robot name (e.g., Claude Code Notification).
4. Important: Select security settings → Signing (Recommended).
5. Copy the generated Webhook URL and Signature key.

3.2 Set Environment Variables

Method 1: System environment variables

# Add to ~/.bashrc or ~/.zshrc
export DINGTALK_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN"
export DINGTALK_SECRET="YOUR_SECRET_KEY"
export DINGTALK_KEYWORDS="Claude,Task completed,Notification"  # Optional

Method 2: Project .env file

# Create a .env file in the project root directory
DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN
DINGTALK_SECRET=YOUR_SECRET_KEY
DINGTALK_KEYWORDS=Claude,Task completed,Notification

Step 4: Restart Claude Code

# Restart Claude Code to load the new MCP configuration
claude code restart
# Or close and reopen Claude Code

Step 5: Verify the Configuration

Run the following commands in Claude Code for testing:

# Test the basic connection
dingtalk_send_text {"content": "🎉 Claude Code DingTalk notification test successful!"}

# Test the session end notification
dingtalk_notify_session_end {
  "sessionType": "Configuration test",
  "summary": "Successfully configured the Claude Code DingTalk notification function"
}

📍 Configuration File Location

Claude Code looks for the .mcp.json configuration in the following locations:

1. Current project directory: ./mcp.json or ./.mcp.json
2. User home directory: ~/.claude/mcp.json
3. Global configuration: ~/.config/claude-code/mcp.json

🔍 Frequently Asked Questions

Q: The dingtalk_xxx command cannot be found? A: Check if the .mcp.json configuration is correct and restart Claude Code.

Q: DingTalk notifications fail to send? A: Check the environment variable configuration and ensure that the Webhook URL and key are correct.

Q: How to confirm if the MCP Server is running? A: In Claude Code, type dingtalk_ and press the Tab key. Available commands should be displayed.

Q: Does it support team-shared configuration? A: Yes, you can share the configuration with your team by committing the .mcp.json file to the code repository.

💻 Usage Examples

Automatic Initialization (Recommended)

If you have set the environment variables, the MCP Server will initialize automatically without manual configuration:

# Send notifications directly without configuration steps
dingtalk_notify_task_complete {
  "taskName": "Project build",
  "status": "success",
  "details": "Build successful, all tests passed",
  "duration": "2 minutes 30 seconds"
}

Manual Configuration Method

If the environment variables are not set, you can manually configure them in Claude Code:

dingtalk_configure {
  "webhook": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN",
  "secret": "YOUR_SECRET_KEY"
}

📚 Documentation

Available Tools

1. dingtalk_configure

Manually configure the DingTalk robot settings.

Parameters:

• webhook (Required): DingTalk robot Webhook URL.
• secret (Optional): Signature verification key.
• keywords (Optional): Array of security keywords.

2. dingtalk_send_text

Send a text message.

Parameters:

• content (Required): Text content.
• atAll (Optional): Whether to @ everyone, default is false.

3. dingtalk_send_markdown

Send a Markdown-formatted message.

Parameters:

• title (Required): Message title.
• text (Required): Markdown-formatted text content.
• atAll (Optional): Whether to @ everyone, default is false.

4. dingtalk_send_link

Send a link message.

Parameters:

• title (Required): Link title.
• text (Required): Link description text.
• messageUrl (Required): Target URL.
• picUrl (Optional): Image URL.

6. dingtalk_notify_session_end

Send a session end notification (New feature).

Parameters:

• sessionType (Optional): Session type, such as "Development assistance", "Code review", "Problem solving", default is "Development assistance".
• duration (Optional): Session duration, such as "30 minutes", "1 hour 20 minutes".
• mainTasks (Optional): List of main tasks.
• summary (Optional): Session summary, default is "Session completed".
• filesCount (Optional): Number of modified/created files, default is 0.
• toolsUsed (Optional): Number of tools/commands used, default is 0.
• atAll (Optional): Whether to @ everyone, default is false.

🎯 Automatic Session End Notifications

Method 1: Direct Call (Recommended)

Call directly at the end of a Claude Code conversation:

dingtalk_notify_session_end {
  "sessionType": "Development assistance",
  "duration": "45 minutes", 
  "mainTasks": ["Implement the DingTalk MCP Server", "Add environment variable support", "Write usage documentation"],
  "summary": "Successfully developed and deployed the DingTalk notification MCP Server, supporting multiple message formats and automatic session notifications",
  "filesCount": 8,
  "toolsUsed": 15
}

Method 2: Trigger via Environment Variables

Set the environment variables and use a script to trigger automatically:

# Set session information
export CLAUDE_SESSION_TYPE="Code review"
export CLAUDE_SESSION_DURATION="30 minutes"
export CLAUDE_MAIN_TASKS="Code quality check, Security vulnerability scan, Performance optimization suggestions"
export CLAUDE_SESSION_SUMMARY="Completed a comprehensive code review, identified and fixed 3 security issues"
export CLAUDE_FILES_COUNT="5"
export CLAUDE_TOOLS_USED="12"

# Trigger the notification
npm run notify-session-end

Method 3: Claude Code Hooks (Automation)

After installing the hook, it will trigger automatically at the end of each session:

# Install the hook
./claude-hook.sh install

# The hook will run automatically at the end of a Claude Code session
# No manual operation required!

💡 Usage Examples

Task Completion Notification

dingtalk_notify_task_complete {
  "taskName": "Code deployment",
  "status": "success",
  "details": "✅ Successfully deployed to the production environment\\n- Version: v2.1.0\\n- Tests: 100% passed\\n- Performance: Optimized by 15%",
  "duration": "3 minutes 45 seconds"
}

Send a Markdown Message

dingtalk_send_markdown {
  "title": "📊 Daily Build Report",
  "text": "## 📊 Daily Build Report\\n\\n**Date**: 2025-01-15\\n**Status**: ✅ Success\\n\\n### 📈 Statistics\\n- Number of builds: 12\\n- Success rate: 100%\\n- Average time: 2 minutes 15 seconds\\n\\n### 🔧 Fixed Issues\\n- Fixed the login timeout issue\\n- Optimized the database query performance\\n\\n---\\n*From Claude Code automated build*"
}

Send Simple Text

dingtalk_send_text {
  "content": "🎉 Code review completed! All check items have passed, and you can start merging into the main branch.",
  "atAll": false
}

🔧 DingTalk Robot Configuration

1. Create a DingTalk Group Robot

1. In the DingTalk group, click Group settings → Intelligent group assistant → Add robot.
2. Select the "Custom" robot.
3. Set the robot name and avatar.
4. Important: Configure the security settings (it is recommended to use the "Signing" method).
5. Obtain the Webhook URL and signature key.

2. Explanation of Security Settings

• Keyword verification: The message must contain the set keywords.
• Signing verification: Use HMAC-SHA256 signature verification (Recommended).
• IP whitelist: Restrict the source IP of requests.

3. Obtain Configuration Information

# Example of Webhook URL
https://oapi.dingtalk.com/robot/send?access_token=f248fa5a2e04cf0c13abb23831c4a6190f3837fa7ddf3338f759db5a67079469

# Example of signature key (signing verification)
SECad12bf23f1e2e3c3d7dae0cd58e41c2b4daa9d1066cdf7ce452c4732ecf0c30e

🚨 Notes

1. Message frequency limit: Each robot can send a maximum of 20 messages per minute.
2. Message format: Ensure that the Markdown format is correct, and special characters need to be escaped.
3. Security configuration: It is recommended to enable signature verification in the production environment.
4. Environment variable priority: Environment variable configuration takes precedence over manual configuration.
5. Error handling: The tool will return a success/failure status. Please check the return value.

🔍 Troubleshooting

Common Issues

Q: The error message "DingTalk client not configured" is displayed. A: Please check the environment variable settings or use dingtalk_configure to configure manually.

Q: Message sending fails? A: Please check the following:

• Whether the Webhook URL is correct.
• Whether the signature key matches.
• Whether the security keyword verification is triggered.
• Whether the frequency limit (20 messages per minute) is exceeded.

Q: npm installation fails? A: Please ensure that the Node.js version is ≥ 18.0.0.

Debug Mode

# Enable debug logging
DEBUG=dingtalk-mcp-server npx claude-code-dingtalk-mcp

🤝 Development and Contribution

Local Development

# Clone the repository
git clone https://github.com/claude-code-community/dingtalk-mcp-server.git
cd dingtalk-mcp-server

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

Project Structure

claude-code-dingtalk-mcp/
├── src/
│   ├── dingtalk.ts     # DingTalk client encapsulation
│   ├── index.ts        # Main program of the MCP Server
│   └── test.ts         # Test cases
├── dist/               # Compiled output
├── .env.example        # Example of environment variables
├── LICENSE             # MIT License
├── README.md           # Documentation
└── package.json        # Project configuration

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Links

• Claude Code Official Documentation
• DingTalk Open Platform Documentation
• Model Context Protocol
• NPM Package

Make task completion notifications in Claude Code more convenient! 🚀