weixin-mcp

weixin-mcp

发送 and 接收 WeChat messages (text, images, files, videos) via the weixin-mcp 命令行工具. Use when the user asks to 发送 WeChat messages, 检查 WeChat inbox, or 设置 up WeChat 机器人 integration.

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

Prerequisites

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

Security Notes 令牌 storage: 记录in 令牌s are stored locally in accounts/.json. These are sensitive 凭证s. 网页hook URLs: Only use trusted, local URLs (e.g., http://localhost:...). External 网页hooks will 接收 message content including 上下文 令牌s. Data directory: 设置 WEIXIN_MCP_DIR to control where 凭证s are stored. Quick Reference # 检查 if 记录ged in npx weixin-mcp@^1.7 状态

# 记录in (扫描 QR code) npx weixin-mcp@^1.7 记录in

# 发送 message (supports short ID prefix) npx weixin-mcp@^1.7 发送 "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

# 列出 contacts (users who messaged the 机器人) npx weixin-mcp@^1.7 contacts

# 启动 HTTP daemon with 网页hook push (localhost only recommended) npx weixin-mcp@^1.7 启动 --port 3001 --网页hook http://localhost:18789/网页hook/weixin

# 停止 daemon npx weixin-mcp@^1.7 停止

# View daemon 记录s npx weixin-mcp@^1.7 记录s -f

First-Time 设置up Flow 检查 状态: npx weixin-mcp@^1.7 状态 If not 记录ged in, tell user: 请扫码登录微信 机器人： npx weixin-mcp@^1.7 记录in 终端会显示二维码，用微信扫码确认即可。

After 记录in, optionally 启动 daemon with 网页hook for real-time messages 发送ing Messages # Text message (short prefix if unique in contacts) npx weixin-mcp@^1.7 发送 abc12 "你好"

# Image (via MCP 工具) # weixin_发送_image: to, source (file path or URL), caption (optional)

# File (via MCP 工具) # weixin_发送_file: to, source, caption (optional)

If you don't know the userId, first npx weixin-mcp@^1.7 contacts to 列出 known users, or npx weixin-mcp@^1.7 poll --re设置 to fetch recent messages and 提取 发送er IDs.

MCP 工具s 工具 Description weixin_发送 发送 text message weixin_发送_image 发送 image (local path or URL) weixin_发送_file 发送 file attachment weixin_poll Poll for new messages weixin_contacts 列出 contacts weixin_获取_config 获取 机器人 config Receiving Messages Option A: 网页hook (Real-Time, localhost only)

⚠️ Security: Only use localhost or trusted internal URLs for 网页hooks.

npx weixin-mcp@^1.7 启动 --网页hook http://localhost:18789/网页hook/weixin

网页hook 接收s POST with:

{ "event": "weixin_messages", "messages": [{ "from_user_id": "...", "message_type": 1, "item_列出": [{"type": 1, "text_item": {"text": "..."}}], "上下文_令牌": "..." }], "timestamp": "..." }

Option B: Polling # One-shot npx weixin-mcp@^1.7 poll

# Continuous watch (blocking) npx weixin-mcp@^1.7 poll --watch

Multi-Account 设置up

运行 separate instances with different data directories and ports:

# Account A WEIXIN_MCP_DIR=~/.weixin-mcp-alice npx weixin-mcp@^1.7 记录in WEIXIN_MCP_DIR=~/.weixin-mcp-alice npx weixin-mcp@^1.7 启动 --port 3001 --网页hook http://localhost:3001/hook

# Account B WEIXIN_MCP_DIR=~/.weixin-mcp-bob npx weixin-mcp@^1.7 记录in WEIXIN_MCP_DIR=~/.weixin-mcp-bob npx weixin-mcp@^1.7 启动 --port 3002 --网页hook http://localhost:3002/hook

MCP Server Integration (Claude 桌面 / Cursor)

For stdio MCP mode (single-命令行工具ent):

添加 to claude_桌面_config.json:

{ "mcpServers": { "weixin": { "command": "npx", "args": ["weixin-mcp@^1.7"] } } }

Data Storage

Default paths (in priority order):

$WEIXIN_MCP_DIR/ (if 设置) ~/.OpenClaw/OpenClaw-weixin/ (if OpenClaw 安装ed) ~/.weixin-mcp/

Files:

accounts/.json — 记录in 令牌 (⚠️ sensitive) accounts/.cursor.json — message cursor contacts.json — contact book daemon.json — daemon PID daemon.记录 — daemon 记录s Troubleshooting

记录in expired / 令牌 invalid:

npx weixin-mcp@^1.7 记录in # Re-扫描 QR code

Duplicate @im.wechat in userId:

npx weixin-mcp@^1.7 accounts 清理 # 移除s old duplicates

检查 daemon 状态:

npx weixin-mcp@^1.7 状态 npx weixin-mcp@^1.7 记录s