WeCom MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to send messages, images, and files to WeCom (Enterprise WeChat) through webhook URLs.

Features

• Send Messages: Send text or markdown formatted messages to WeCom groups
• Send Images: Upload and send images from local files or URLs
• Send Files: Upload and send various file types to WeCom
• Mention Users: Support for mentioning specific users by ID or mobile number
• Error Handling: Comprehensive error handling with detailed error codes
• Environment-based Configuration: Secure webhook URL management through environment variables

Prerequisites

• Node.js 18+
• A WeCom webhook URL (obtain from your WeCom group settings)

Getting Your WeCom Webhook URL

1. Open WeCom (Enterprise WeChat)
2. Go to the group where you want to receive messages
3. Click on group settings (⚙️)
4. Select "Group Bots" or "群机器人"
5. Add a new bot and copy the webhook URL

The webhook URL format: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY

Installation & Setup

MCP Configuration

Add this server to your MCP settings configuration file with your webhook URL:

For Claude Desktop (MacOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wecom": {
      "command": "npx",
      "args": ["wecom-mcp"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
      }
    }
  }
}

For Claude Desktop (Windows)

Edit %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wecom": {
      "command": "npx",
      "args": ["wecom-mcp"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
      }
    }
  }
}

For Other MCP Clients

Use the following configuration:

{
  "command": "npx",
  "args": ["wecom-mcp"],
  "env": {
    "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
  }
}

Environment Variables

The server requires the following environment variable:

• WECOM_WEBHOOK_URL (required): Your WeCom webhook URL

Available Tools

1. send_message

Send text or markdown messages to WeCom.

Parameters:

• content (required): Message content
• msg_type (optional): Message type - "text" or "markdown" (default: "markdown")
• mentioned_list (optional): Array of user IDs to mention
• mentioned_mobile_list (optional): Array of mobile numbers to mention

Example:

{
  "name": "send_message",
  "arguments": {
    "content": "🚀 Deployment completed successfully!",
    "msg_type": "markdown"
  }
}

2. send_wecom_image

Send images to WeCom.

Parameters:

• image_path (required): Local file path or URL to the image

Example:

{
  "name": "send_wecom_image",
  "arguments": {
    "image_path": "/path/to/image.png"
  }
}

3. send_wecom_file

Send files to WeCom.

Parameters:

• file_path (required): Local file path

Example:

{
  "name": "send_wecom_file",
  "arguments": {
    "file_path": "/path/to/document.pdf"
  }
}

Usage Examples

Once configured, you can ask your AI assistant to:

• "Send a message to my WeCom group saying 'Hello team!'"
• "Upload this image to WeCom" (with image attached)
• "Send this document to my WeCom group"
• "Send a markdown message with status update"

The webhook URL is automatically used from the environment variable, so you don't need to specify it in each request.

Error Handling

The server provides detailed error messages for common issues:

• VALIDATION_ERROR: Invalid input parameters or missing environment variables
• NETWORK_ERROR: Network connectivity issues
• API_FAILURE: WeCom API errors
• FILE_ERROR: File access or format issues

Development

To run locally for development:

# Clone the repository
git clone <repository-url>
cd wecom-mcp

# Install dependencies
npm install

# Set your webhook URL
export WECOM_WEBHOOK_URL="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"

# Build the project
npm run build

# Run the server
npm start

# Run tests
node dist/test-client.js

Testing

The project includes a comprehensive test client that validates all functionality:

# Set environment variable and run tests
export WECOM_WEBHOOK_URL="YOUR_WEBHOOK_URL"
npm run build
node dist/test-client.js

The test client will:

• List available tools
• Send a test message
• Send a test image
• Send a test file

Supported File Types

Images

• JPG/JPEG
• PNG
• Size limit: 5 bytes - 2MB

Files

• Any file type supported by WeCom
• Size limit: Up to 20MB

Security Notes

• Store your webhook URL securely as an environment variable
• Never commit webhook URLs to version control
• The webhook URL contains sensitive access keys

License

ISC

Contributing

Issues and pull requests are welcome! Please feel free to contribute to improve this MCP server.