weixin-mcp

Send and receive WeChat messages (text, images, files, videos) via the weixin-mcp CLI. Use when the user asks to send WeChat messages, check WeChat inbox, or set up WeChat bot integration.

Source: github.com/bkmashiro/weixin-mcp
npm: weixin-mcp

Prerequisites

No installation needed — uses npx weixin-mcp@^1.7 directly (version pinned for security).

Security Notes

• Token storage: Login tokens are stored locally in accounts/<id>.json. These are sensitive credentials.
• Webhook URLs: Only use trusted, local URLs (e.g., http://localhost:...). External webhooks will receive message content including context tokens.
• Data directory: Set WEIXIN_MCP_DIR to control where credentials are stored.

Quick Reference

# Check if logged in
npx weixin-mcp@^1.7 status

# Login (scan QR code)
npx weixin-mcp@^1.7 login

# Send message (supports short ID prefix)
npx weixin-mcp@^1.7 send <userId> "message text"

# Poll for new messages (one-shot)
npx weixin-mcp@^1.7 poll

# Watch for messages (continuous)
npx weixin-mcp@^1.7 poll --watch

# List contacts (users who messaged the bot)
npx weixin-mcp@^1.7 contacts

# Start HTTP daemon with webhook push (localhost only recommended)
npx weixin-mcp@^1.7 start --port 3001 --webhook http://localhost:18789/webhook/weixin

# Stop daemon
npx weixin-mcp@^1.7 stop

# View daemon logs
npx weixin-mcp@^1.7 logs -f

First-Time Setup Flow

1. Check status: npx weixin-mcp@^1.7 status
2. If not logged in, tell user:

   请扫码登录微信 bot：
   npx weixin-mcp@^1.7 login
   终端会显示二维码，用微信扫码确认即可。
   

3. After login, optionally start daemon with webhook for real-time messages

Sending Messages

# Text message (short prefix if unique in contacts)
npx weixin-mcp@^1.7 send abc12 "你好"

# Image (via MCP tool)
# weixin_send_image: to, source (file path or URL), caption (optional)

# File (via MCP tool)  
# weixin_send_file: to, source, caption (optional)

If you don't know the userId, first npx weixin-mcp@^1.7 contacts to list known users, or npx weixin-mcp@^1.7 poll --reset to fetch recent messages and extract sender IDs.

MCP Tools

Receiving Messages

Option A: Webhook (Real-Time, localhost only)

⚠️ Security: Only use localhost or trusted internal URLs for webhooks.

npx weixin-mcp@^1.7 start --webhook http://localhost:18789/webhook/weixin