wechatbot-mcp

OpenCode / MCP server wrapping @wechatbot/wechatbot — the official WeChat iLink Bot SDK (Tencent partner program, not a hook / reverse-engineered client).

Lets any Agent (OpenCode, Claude Code, Cursor, etc.) read and reply to WeChat messages over MCP stdio.

Quick start

npm install
npm run build
node dist/index.js                  # stdio MCP server

Register with OpenCode in ~/.config/opencode/opencode.json:

{
  "mcp": {
    "wechatbot": {
      "type": "local",
      "command": ["node", "<absolute-path>/wechatbot-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

Then ask your Agent to call wechat_login once. A QR code PNG is auto-opened on screen; scan with WeChat. Credentials are persisted to ~/.wechatbot/credentials/ for ~14 days — subsequent restarts re-auth silently without a QR.

Tools

Tool	Description
wechat_login	Login. Silent re-auth from disk if creds exist; otherwise renders a QR PNG.
wechat_logout	Stop polling. clearCredentials:true wipes on-disk creds.
wechat_status	Connection state, account, queue depth, known-user count.
wechat_send_text	Send a text message. SDK auto-splits on natural paragraphs.
wechat_send_image	Send a local image file (optional caption).
wechat_send_file	Send any local file — auto-routes by extension (.png → image, .mp4 → video, else file).
wechat_send_url	Send media from a remote URL. SDK downloads and uploads to WeChat CDN.
wechat_send_typing / wechat_stop_typing	Show / cancel "对方正在输入中…".
wechat_pending_messages	Drain received messages (images/files auto-downloaded to ~/.wechatbot/pending-media/).
wechat_known_users	List user IDs we have a context_token for (i.e. who can be replied to).

Protocol note (anti-spam)

WeChat iLink requires the recipient to message you first before you can reply. wechat_send_* tools return a clear error listing known users when the target isn't in that set. Always wechat_pending_messages first to learn user IDs from inbound messages.

Storage layout

~/.wechatbot/
├── credentials/     # iLink tokens (auto-managed, ~14-day TTL)
├── mcp/             # rendered QR PNGs (qr-*.png) + ASCII fallback (qr-latest.txt)
└── pending-media/   # media auto-downloaded from received messages

Architecture

   ┌────────────────┐
   │  WeChat user   │
   └────────┬───────┘
            │ iLink Bot protocol (Tencent)
   ┌────────▼───────┐
   │ @wechatbot/    │  ← npm SDK (long-poll, login, send, media)
   │   wechatbot    │
   └────────┬───────┘
            │ IncomingMessage + SendContent
   ┌────────▼───────┐
   │  BotManager    │  ← this repo: lifecycle, queue, snapshot
   └────────┬───────┘
            │ tools/call JSON-RPC
   ┌────────▼───────┐
   │  MCP server    │  ← stdio transport, 11 tools
   │  (this repo)   │
   └────────┬───────┘
            │ stdin/stdout
   ┌────────▼───────┐
   │ OpenCode / LLM │
   └────────────────┘

Tested with

• Node.js ≥ 22 (tested on 24.11)
• @wechatbot/wechatbot ^2.2.0
• @modelcontextprotocol/sdk ^1.0
• Windows 10/11 (PowerShell + cmd)

24/7 background auto-reply (optional)

A standalone daemon (scripts/wechat-daemon.mjs) runs the MCP server in a child process and auto-replies to incoming messages. Useful when OpenCode is closed or you're AFK.

# Default: none mode — log only, NO auto-reply (recommended unless you
# explicitly want a bot running 24/7)
node scripts/wechat-daemon.mjs

# LLM mode: shell out to any command, message JSON via stdin, reply = stdout
node scripts/wechat-daemon.mjs --reply-mode=llm --llm-cmd "opencode run --message"

# echo mode: just echo back the user's text (testing only — NOT recommended)
node scripts/wechat-daemon.mjs --reply-mode=echo

# Whitelist specific userIds (others get silently logged but no reply)
node scripts/wechat-daemon.mjs --reply-mode=llm --llm-cmd "..." \
    --allowed-users="o9cq804w_6mDSHAhyIQnPntiKI4c@im.wechat"

# Customize the AI-label prefix (default: "[ai助手]")
node scripts/wechat-daemon.mjs --reply-mode=llm --llm-cmd "..." --reply-prefix="[bot]"

# Tune cadence and log path
node scripts/wechat-daemon.mjs --poll-interval=1000 --log-file=/path/to/daemon.log

Every non-empty reply is auto-prefixed with [ai助手] (configurable via --reply-prefix) so recipients can tell the message came from an AI, not from the user themselves. This applies to all reply modes that produce output (echo, llm).

Logs go to both stderr (visible in your terminal) and ~/.wechatbot/daemon.log (persistent). Use Task Scheduler / nohup / pm2 / Windows Service to keep it running across reboots.

Concurrency note: only ONE listener per WeChat account. If you also run the OpenCode skill below, pick one — both will race on wechat_pending_messages (the queue is consumed atomically on each drain).

OpenCode skill (optional)

A user-global skill wechat-monitor makes OpenCode itself run the polling loop within an interactive session. The agent sees each incoming message and replies through the same MCP tools, with full LLM reasoning.

Install location: ~/.claude/skills/wechat-monitor/SKILL.md (auto-discovered by OpenCode alongside the bundled wps-* / mmx-cli skills).

Trigger: type /skill wechat-monitor or say "monitor wechat" / "wechat 监控".

The skill's SKILL.md documents the loop, concurrency rules, and reply strategies — agent reads it on invocation.

License

MIT