weixin

WeChat Channel Plugin for Claude Code

Chat with Claude Code from WeChat via Tencent's official iLink Bot API.

Features

• Two-way messaging between WeChat and Claude Code
• QR code login (no reverse engineering, uses official API)
• Access control with pairing codes and allowlists
• Typing indicators
• Long message chunking (4000 char limit per message)
• Permission relay (approve/deny tool use from WeChat)
• Multi-user support with independent sessions
• Orphan process watchdog

Prerequisites

• Bun v1.0+
• Claude Code v2.1.80+
• A WeChat account (for QR code login)

Quick Start

1. Clone and install

git clone https://github.com/user/claude-code-weixin.git
cd claude-code-weixin
bun install

2. Register the MCP server

Add to your project .mcp.json (or ~/.claude.json for global):

{
  "mcpServers": {
    "weixin": {
      "command": "bun",
      "args": ["run", "--cwd", "/path/to/claude-code-weixin", "--shell=bun", "--silent", "start"]
    }
  }
}

3. Start Claude Code with the channel flag

claude --dangerously-load-development-channels server:weixin

On first run, the plugin prints a QR code URL to stderr. Open it in a browser and scan with WeChat to authenticate.

4. Pair your WeChat account

Send any message to the bot from WeChat. You'll receive a 5-letter pairing code. In Claude Code, run:

/weixin:access pair <code>

Done! Messages you send on WeChat will now appear in Claude Code, and Claude will reply back to you on WeChat.

Access Control

The plugin supports four DM policies:

Policy	Behavior
pairing (default)	New users must pair via code before chatting
allowlist	Only pre-approved user IDs can chat
open	Anyone can chat (not recommended)
disabled	All incoming messages are dropped

Manage access with the /weixin:access skill:

/weixin:access                  # Show status
/weixin:access pair <code>      # Approve a pairing
/weixin:access deny <code>      # Reject a pairing
/weixin:access allow <userId>   # Add user to allowlist
/weixin:access remove <userId>  # Remove user from allowlist
/weixin:access policy <mode>    # Set DM policy

Architecture

WeChat User  <-->  iLink Bot API  <-->  Plugin (MCP Server)  <-->  Claude Code
                   (long-poll)           (Bun + stdio)              (session)

• Inbound: Plugin long-polls getupdates, forwards messages as MCP channel notifications
• Outbound: Claude calls the reply tool, plugin sends via sendmessage API
• State: ~/.claude/channels/weixin/ (credentials, access config, context tokens)

State Files

File	Purpose
credentials.json	Bot token and login info (auto-created on QR login)
access.json	Allowlist and pending pairing codes
context_tokens.json	Per-user context tokens for reply routing
bot.pid	Process ID for orphan detection

How It Works

This plugin uses Tencent's official iLink Bot API (ilinkai.weixin.qq.com) which provides legitimate bot access to personal WeChat accounts. The API uses:

• QR code authentication (same flow as WeChat Web login)
• HTTP long-polling for receiving messages (getupdates)
• HTTP POST for sending messages (sendmessage)
• Context tokens that must be echoed back with each reply

The plugin runs as an MCP server connected to Claude Code via stdio. It declares the claude/channel experimental capability so Claude Code registers it as a channel and displays incoming messages in the session.

Troubleshooting

MCP shows "failed": Kill stale bun processes (pkill -f 'bun.*weixin') and reconnect via /mcp.

QR code expired: Delete ~/.claude/channels/weixin/credentials.json and restart.

Messages not arriving: Check that your user ID is in the allowlist (/weixin:access).

Session expired (-14): The plugin auto-detects this and triggers re-login with a new QR code.

License

Apache 2.0