wecom-mcp/README.md

WeCom MCP Server for sending messages to WeCom

# 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`:

```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`:

```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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```bash
# 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:

```bash
# 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.