📦

wecom-bot-server

Model Context Protocol (MCP) server for WeCom Bot message sending

0 installs

Trust: 39 — Low

Comms

Installation

npx @futuretea/wecom-bot-mcp-server

Ask AI about wecom-bot-server

I know everything about wecom-bot-server. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

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

Command-line flags
Environment variables (prefix: WECOM_MCP_)
Configuration file
Default values

CLI Options

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

Option	Description	Default
`--config`	Config file path (YAML)
`--port`	Port for HTTP/SSE mode (0 = stdio mode)	`0`
`--sse-base-url`	Public base URL for SSE endpoint
`--log-level`	Log level (0-9)	`5`
`--wecom-bot-key`	WeCom bot webhook key (required)
`--enabled-tools`	Specific tools to enable
`--disabled-tools`	Specific tools to disable

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_text

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

Parameter	Type	Required	Description
`content`	string	Yes	The text content to send. Maximum 2048 bytes.
`mentioned_list`	string[]	No	List of user IDs to @mention. Use `"@all"` to mention everyone.
`mentioned_mobile_list`	string[]	No	List of mobile numbers to @mention. Use `"@all"` to mention everyone.

Example:

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

send_markdown

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

Parameter	Type	Required	Description
`content`	string	Yes	The markdown content to send. Maximum 4096 bytes.

Example:

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

send_image

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

Parameter	Type	Required	Description
`base64`	string	Yes	Base64-encoded image content. Max image size: 2MB. Supported formats: JPG, PNG.
`md5`	string	Yes	MD5 hash of the original image content (before base64 encoding).

Example:

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

send_news

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

Parameter	Type	Required	Description
`articles`	object[]	Yes	Array of news articles (1–8 items).
`articles[].title`	string	Yes	Article title.
`articles[].description`	string	No	Article description.
`articles[].url`	string	Yes	Article link URL.
`articles[].picurl`	string	No	Article cover image URL.

Example:

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

send_text_notice_card

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

Parameter	Type	Required	Description
`main_title`	string	Yes	Main title of the card.
`main_title_desc`	string	No	Description text below the main title.
`sub_title`	string	No	Subtitle text displayed in the card body.
`source`	object	No	Source information displayed at the top of the card.
`source.icon_url`	string	No	URL of the source icon.
`source.desc`	string	No	Source description text.
`emphasis_content`	object	No	Emphasized content area (large text).
`emphasis_content.title`	string	No	Emphasis title (displayed in large font).
`emphasis_content.desc`	string	No	Emphasis description.
`horizontal_content_list`	object[]	No	Key-value pairs displayed horizontally.
`horizontal_content_list[].keyname`	string	Yes	Key name (label).
`horizontal_content_list[].value`	string	No	Value text.
`jump_list`	object[]	No	Jump links displayed at the bottom of the card.
`jump_list[].title`	string	Yes	Jump link title.
`jump_list[].url`	string	Yes	Jump link URL.
`card_action`	object	Yes	Card click action.
`card_action.url`	string	Yes	URL to open when the card is clicked.

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_news_notice_card

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

Parameter	Type	Required	Description
`main_title`	string	Yes	Main title of the card.
`main_title_desc`	string	No	Description text below the main title.
`card_image_url`	string	Yes	URL of the card cover image.
`source`	object	No	Source information displayed at the top of the card.
`source.icon_url`	string	No	URL of the source icon.
`source.desc`	string	No	Source description text.
`card_action`	object	Yes	Card click action.
`card_action.url`	string	Yes	URL to open when the card is clicked.

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_file

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

Parameter	Type	Required	Description
`filename`	string	Yes	Name of the file to upload.
`base64_data`	string	Yes	Base64-encoded file content. Max file size: 20MB.

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

wecom-bot-server

Installation

Reviews

Documentation

WeCom Bot MCP Server

Features

Getting Started

Requirements

Claude Code

VS Code / Cursor

Docker

Configuration

CLI Options

Configuration File

Environment Variables

HTTP/SSE Mode

Tools

Development

Build

Test

Lint

Run with mcp-inspector

Contributing

License

Tags

Security Checklist