文档

MCP 服务

一条命令让 agent 直接操作微信。默认只读、默认只听本机。

起服务

python -m wx4auto mcp                  # stdio（本地 agent 最常用），默认只读
python -m wx4auto mcp --allow-write    # 放开写操作
python -m wx4auto mcp --list-tools     # 看有哪些工具
python -m wx4auto mcp --self-test      # 自检（不发任何消息）

接到 Claude Desktop / Cursor / 任何兼容 MCP 的客户端：

{
  "mcpServers": {
    "wechat": {
      "command": "python",
      "args": ["-m", "wx4auto", "mcp", "--allow-write"]
    }
  }
}

工具一览（15 个）

只读（默认暴露） 写（需 --allow-write）
wechat_status 整体体检 wechat_send_message 发消息
wechat_sessions 会话列表 wechat_send_file 发文件
wechat_messages 读消息 wechat_send_emoji 发表情（支持「可怜兮兮」这种含义输入）
wechat_media_content 取图片/视频/表情的实际内容 wechat_switch_chat 切会话
wechat_contacts 通讯录 wechat_wait_message 阻塞等一条消息
wechat_group_members 群成员 wechat_send_later 定时发送
wechat_moments 朋友圈全量历史 wechat_revoke_last 撤回最后一条
wechat_vision_doctor 媒体能力体检

wechat_media_content 是给「多模态大脑」准备的：让 agent 一次性拿到某个会话里 最近的图片 / 视频 / 表情的本机文件路径（图片已自动转成 jpg， 表情是原始 GIF/JPEG 且带 caption），agent 再把这些路径交给多模态模型即可。

默认姿态刻意保守

「能读你全部聊天、能替你发消息」的能力一旦挂到网上就很危险，所以默认：

  • 默认只读 —— 7 个写工具要显式 --allow-write 才出现在 tools/list 里
  • 默认只听 127.0.0.1；绑非本机时强制要求 token （不给就拒绝启动，不会悄悄裸奔）
  • --tools / --exclude-tools 精细控制暴露面
  • --write-limit（默认 30 次/分钟）防手滑刷屏

分享给别人用（HTTP + 令牌）

python -m wx4auto mcp --transport http --host 0.0.0.0 --port 8765 \
    --token <一串足够长的口令> --allow-write

兼容两种传输：POST /mcp（Streamable HTTP，按 Accept 返回 JSON 或单帧 SSE） 与 GET /sse + POST /messages?sessionId=（旧版 SSE）。GET /health 也要求鉴权。

部署拓扑：服务必须和它要操作的微信在同一台机器

这一条最容易误解：

你想做的事 结论 怎么做
别人用你的微信（他的 agent 遥控你的电脑） ✅ 可以 你在自己电脑上跑 HTTP 服务，把地址 + token 给他
别人操作他自己的微信 ✅ 可以，但不是连你的服务 他在他自己电脑上装 wx4auto（stdio 最好，连网络都不需要）
用你的服务去操作别人电脑上的微信 ❌ 做不到 见下

为什么做不到：wx4auto 干的是两件纯本地的事 ——

  1. 用 Windows UI Automation 驱动本机那个已登录的微信桌面客户端
  2. 读本机数据库时，靠扫描本机 Weixin.exe 进程内存拿到密钥（只读、不注入）

没有任何「跟微信服务器通信」的协议（这是有意不做的）。 所以服务端在哪台机器，被操作的就是哪台机器上的那个微信， 跟调用方在哪毫无关系。

多开怎么办：同一台机器上开了多个微信，可以指定目标 —— WeChat(nickname="某个昵称") 选窗口，WeChatDB(account="wxid_xxx") 选数据库。 但仍然只能是本机的那些账号。

分享给别人时的实操建议

  • 优先局域网 / VPN，别直接怼公网。要过公网就套一层反向代理 + HTTPS， 并确认防火墙只放行你需要的来源 IP。
  • token 给长一点（服务端只做等值比较，别用短口令）。
  • 只想让他「看」就给他只读： --tools wechat_status,wechat_sessions,wechat_messages,wechat_moments —— 写工具根本不会出现在 tools/list 里，他连调用入口都没有。
  • 没有「按调用方隔离」：能连上的调用方共享同一个微信 （同一份聊天记录、同一个发信身份）。不要把 token 给不信任的人。
  • 所有人共用一个微信界面，操作是串行的（服务端一条专用工作线程排队）， 并发请求会互相等待，不会交叉点错。
  • 分享代码比分享服务安全得多 —— 对方在自己机器上跑，数据不出他的电脑。

两个实现要点

1. 必须用一条专用工作线程跑所有微信操作

ThreadingHTTPServer 的请求在新建线程里执行， 而 UIA / COM 要求每个线程自己 CoInitialize —— 不这么做会一调微信就报 CoInitialize has not been called， 现象是「HTTP 调用总是返回一个很短的错误报文」，很容易误判成协议写错了。

顺带这条线程让微信操作天然串行 （UIA 并发会互相抢焦点 → 发错人）。

2. 协议手写即可

MCP 的核心面很窄（initialize / tools/list / tools/call）， 按 2024-11-05 规范收发 JSON-RPC 就能被客户端认。零依赖，不给发布包添 SDK。

--self-test 里有真·stdio 子进程互操作验证 （拉起 python -m wx4auto mcp 子进程对话）。