WeComBot MCP Server

A Model Context Protocol (MCP) server for WeChat Work (企业微信) group bot integration. Send messages to WeChat Work groups directly from any MCP-compatible client.

中文文档 | English

Features

• 🚀 Multiple Message Types: Text, Markdown, Image, and News messages
• 🔄 MCP 1.0 Compatible: Works with Claude Desktop, Continue, Cline, and other MCP clients
• 📝 Rich Text Support: Full Markdown formatting support
• 👥 Mention Support: @all and specific user mentions
• 🖼️ Image Messages: Base64 image support with automatic MD5 generation
• 📰 News Cards: Rich link preview cards
• ✅ Type Safe: Full TypeScript implementation
• 🛠️ Easy Configuration: Simple environment variable setup

Quick Start

Prerequisites

• Node.js 18+
• A WeChat Work group bot webhook URL
• An MCP-compatible client (Claude Desktop, Continue, Cline, etc.)

Installation

# Install globally via npm
npm install -g @kedoupi/wecombot-mcp

# Or use directly with npx (recommended)
npx @kedoupi/wecombot-mcp

Development Installation

# Clone the repository for development
git clone https://github.com/kedoupi/wecombot-mcp.git
cd wecombot-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Get WeChat Work Webhook URL

   • Create a group bot in your WeChat Work group
   • Copy the webhook URL (format: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY)

2. Configure MCP Client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "wecombot": {
      "command": "node",
      "args": ["/path/to/wecombot-mcp/dist/index.js"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
      }
    }
  }
}

Continue/Cline (VS Code)

Add to your MCP configuration:

{
  "mcpServers": [
    {
      "name": "wecombot",
      "command": "node",
      "args": ["/path/to/wecombot-mcp/dist/index.js"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
      }
    }
  ]
}

3. Restart your MCP client to load the new server

Usage

Text Message

{
  "name": "send_wecom_message",
  "arguments": {
    "message_type": "text",
    "content": "Hello, World! 🌍"
  }
}

Markdown Message

{
  "name": "send_wecom_message",
  "arguments": {
    "message_type": "markdown",
    "content": "# Project Update\n\n**Status**: ✅ Complete\n\n- Feature A implemented\n- Tests passing\n- Ready for deployment\n\n> Great work team!"
  }
}

Mention Message

{
  "name": "send_wecom_message",
  "arguments": {
    "message_type": "text",
    "content": "Meeting starts in 10 minutes!",
    "mentioned_list": ["@all"]
  }
}

News/Link Card

{
  "name": "send_wecom_message",
  "arguments": {
    "message_type": "news",
    "content": "Learn about the latest developments in AI and MCP integration.",
    "title": "🤖 Model Context Protocol Guide",
    "description": "Complete guide to building MCP servers",
    "url": "https://modelcontextprotocol.io/",
    "picurl": "https://example.com/thumbnail.jpg"
  }
}

Image Message

{
  "name": "send_wecom_message",
  "arguments": {
    "message_type": "image",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
  }
}

API Reference

Tool: send_wecom_message

Send a message to WeChat Work group via webhook.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | message_type | string | Yes | Message type: text, markdown, image, or news | | content | string | Yes | Message content or base64 image data | | mentioned_list | string[] | No | List of users to mention (use @all for everyone) | | title | string | No | Title for news message (required for news type) | | description | string | No | Description for news message | | url | string | No | URL for news message (required for news type) | | picurl | string | No | Picture URL for news message |

Response

{
  "content": [
    {
      "type": "text",
      "text": "Message sent successfully to WeChat Work group. Type: text"
    }
  ]
}

Development

Running Tests

# Run all tests
npm test

# Run tests in development mode
npm run test:dev

# Test with real webhook (requires WECOM_WEBHOOK_URL)
node test-real-webhook.js

# Test MCP server functionality
node test-mcp-server.js

Development Mode

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

Project Structure

wecombot-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── wecom-client.ts   # WeChat Work API client
│   ├── types.ts          # TypeScript type definitions
│   └── test/             # Test files
├── dist/                 # Compiled JavaScript
├── test-*.js            # Integration test scripts
└── README.md            # This file

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Use TypeScript for all new code
• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

Testing

The project includes comprehensive tests:

• Unit Tests: Core functionality testing
• Integration Tests: Real webhook testing
• MCP Protocol Tests: Protocol compliance testing
• Compatibility Tests: Multi-client compatibility

See TEST_REPORT.md for detailed test results.

Troubleshooting

Common Issues

1. Server not starting

   • Check that Node.js 18+ is installed
   • Verify the webhook URL is set correctly
   • Ensure the project is built (npm run build)

2. Messages not sending

   • Verify the webhook URL is valid
   • Check that the bot has permission to send messages
   • Ensure the group bot is properly configured

3. MCP client not connecting

   • Verify the server path in client configuration
   • Check that the environment variables are set
   • Restart the MCP client after configuration changes

Debug Mode

# Enable debug logging
DEBUG=wecombot* npm start

# Test with verbose output
npm run test:dev -- --verbose

License

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

Acknowledgments

• Model Context Protocol for the MCP specification
• WeChat Work API for the webhook integration
• Anthropic for MCP SDK and tools

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Wiki

Made with ❤️ for the MCP community