WeCom Bot MCP Server

Features | Getting Started | Configuration | Tools | Development

Features

A Model Context Protocol (MCP) server for WeCom (WeChat Work) bot webhooks.

• Text Messages: Send plain text with @mention support (by user ID or mobile number)
• Markdown Messages: Send Markdown-formatted messages (headings, bold, links, quotes, etc.)
• Image Messages: Send base64-encoded images (JPG/PNG, up to 2MB)
• News Messages: Send article list cards (1–8 articles with title, description, URL, cover image)
• Template Cards: Send text notice and news notice template cards with highlighted content, key-value pairs, links, and click actions
• File Upload: Upload files to WeCom server (up to 20MB) and get back a media_id
• Dual Transport: Runs in stdio mode (for MCP client integration) or HTTP/SSE mode (for network access)
• Cross-platform: Available as native binaries (Linux, macOS, Windows — amd64/arm64), an npm package, or Docker images

Getting Started

Requirements

• A WeCom bot webhook key (from the webhook URL: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY)

Claude Code

claude mcp add wecom-bot -- npx @futuretea/wecom-bot-mcp-server@latest \
  --wecom-bot-key YOUR_KEY

VS Code / Cursor

Add to .vscode/mcp.json or ~/.cursor/mcp.json:

{
  "servers": {
    "wecom-bot": {
      "command": "npx",
      "args": [
        "-y",
        "@futuretea/wecom-bot-mcp-server@latest",
        "--wecom-bot-key",
        "YOUR_KEY"
      ]
    }
  }
}

Docker

Stdio mode:

docker run --rm -i ghcr.io/futuretea/wecom-bot-mcp-server:latest \
  --wecom-bot-key YOUR_KEY

HTTP/SSE mode:

docker run --rm -p 8080:8080 ghcr.io/futuretea/wecom-bot-mcp-server:latest \
  --port 8080 --wecom-bot-key YOUR_KEY

Configuration

Configuration can be set via CLI flags, environment variables, or a config file.

Priority (highest to lowest):

1. Command-line flags
2. Environment variables (prefix: WECOM_MCP_)
3. Configuration file
4. Default values

CLI Options

npx @futuretea/wecom-bot-mcp-server@latest --help

Configuration File

Create config.yaml:

port: 0  # 0 for stdio, or set a port like 8080 for HTTP/SSE

log_level: 5

# Get the key from your WeCom bot webhook URL:
# https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY_HERE
wecom_bot_key: your-bot-key-here

# enabled_tools: []
# disabled_tools: []

Environment Variables

Use WECOM_MCP_ prefix with underscores:

WECOM_MCP_PORT=8080
WECOM_MCP_WECOM_BOT_KEY=your-key
WECOM_MCP_LOG_LEVEL=5

HTTP/SSE Mode

Run with a port number for network access:

wecom-bot-mcp-server --port 8080 --wecom-bot-key YOUR_KEY

Endpoints:

• /healthz - Health check
• /mcp - Streamable HTTP endpoint
• /sse - Server-Sent Events endpoint
• /message - Message endpoint for SSE clients

With a public URL behind a proxy:

wecom-bot-mcp-server --port 8080 \
  --sse-base-url https://your-domain.com:8080 \
  --wecom-bot-key YOUR_KEY

Tools

Use --enabled-tools / --disabled-tools for fine-grained control.

Send a text message through a WeCom bot webhook. Supports @mentioning users by ID or mobile number.

Example:

{
  "content": "Hello, this is a test message.",
  "mentioned_list": ["user1", "user2"],
  "mentioned_mobile_list": ["13800138000"]
}

Send a Markdown message through a WeCom bot webhook. Supports headings, bold, links, quotes, etc.

Example:

{
  "content": "# Heading\n**Bold text**\n> Quote\n[Link](https://example.com)"
}

Send an image (JPG/PNG, base64-encoded) through a WeCom bot webhook.

Example:

{
  "base64": "iVBORw0KGgoAAAANS...",
  "md5": "d41d8cd98f00b204e9800998ecf8427e"
}

Send a news message (article list) through a WeCom bot webhook. Accepts 1–8 articles.

Example:

{
  "articles": [
    {
      "title": "Breaking News",
      "description": "Something important happened.",
      "url": "https://example.com/news/1",
      "picurl": "https://example.com/cover.jpg"
    }
  ]
}

Send a text notice template card through a WeCom bot webhook. Supports highlighted content, key-value pairs, and links.

Example:

{
  "main_title": "Deployment Notification",
  "main_title_desc": "Production environment",
  "source": {
    "icon_url": "https://example.com/icon.png",
    "desc": "CI/CD Pipeline"
  },
  "emphasis_content": {
    "title": "SUCCESS",
    "desc": "Build #1234"
  },
  "horizontal_content_list": [
    { "keyname": "Branch", "value": "main" },
    { "keyname": "Commit", "value": "abc1234" }
  ],
  "jump_list": [
    { "title": "View Details", "url": "https://example.com/build/1234" }
  ],
  "card_action": {
    "url": "https://example.com/build/1234"
  }
}

Send a news notice template card with a cover image through a WeCom bot webhook.

Example:

{
  "main_title": "New Feature Released",
  "main_title_desc": "v2.0.0 is now available",
  "card_image_url": "https://example.com/banner.jpg",
  "source": {
    "icon_url": "https://example.com/icon.png",
    "desc": "Product Team"
  },
  "card_action": {
    "url": "https://example.com/changelog"
  }
}

Upload a file to the WeCom server (up to 20MB). Returns a media_id you can use to send file messages.

Example:

{
  "filename": "report.pdf",
  "base64_data": "JVBERi0xLjQK..."
}

Development

Build

make build

Test

go test ./...

Lint

make lint

Run with mcp-inspector

npx @modelcontextprotocol/inspector@latest -- npx @futuretea/wecom-bot-mcp-server@latest

Contributing

Found a bug or have an idea? Open an issue or send a pull request on GitHub.

License

Apache-2.0