mcp-wechat-server

基于 MCP（Model Context Protocol）的微信机器人服务器，让任何 AI Agent 都能收发微信消息。

功能

• 6 个 MCP 工具：登录、消息轮询、文本发送、打字状态
• 扫码登录：生成终端文本二维码、PNG 图片、URL 链接三种方式
• 长轮询监听：阻塞等待新消息，最长可等待 7 天
• 打字状态：Agent 处理消息时自动显示"对方正在输入..."
• 状态持久化：重启不丢失登录凭证和消息游标
• 独立运行：无需 OpenClaw 框架，开箱即用

快速开始

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "wechat": {
      "command": "bunx",
      "args": ["mcp-wechat-server"]
    }
  }
}

OpenCode

在 opencode.json 中添加：

{
  "mcp": {
    "wechat": {
      "type": "local",
      "command": ["bunx", "mcp-wechat-server"],
      "enabled": true
    }
  }
}

Cursor / 其他 MCP 客户端

{
  "command": "bunx",
  "args": ["mcp-wechat-server"]
}

bunx 会自动从 npm 下载并运行，无需手动安装。

环境要求

• Bun >= 1.0.0

使用方法

1. 扫码登录

AI Agent 调用 login_qrcode 生成二维码，你可以通过以下方式扫码：

• 在终端运行 cat ~/.mcp-wechat-server/qrcode.txt 查看二维码
• 打开图片文件 ~/.mcp-wechat-server/qrcode.png
• 将链接复制到微信中打开

提示：如果手机扫码后页面一直加载，请切换到移动数据网络（关闭 WiFi）。

<img src="assets/opencode_screenshot1.png" alt="OpenCode 登录二维码" width="600">

2. 确认登录

Agent 调用 check_qrcode_status 确认登录状态。

3. 开始聊天

登录成功后，Agent 会自动执行以下流程：

1. 调用 get_messages 轮询新消息
2. 收到消息后调用 send_typing 显示"正在输入..."
3. 处理完成后调用 send_text_message 回复
4. 回复完毕后调用 send_typing 取消打字状态

<img src="assets/wechat_screenshot1.jpg" alt="微信收发消息" width="400">

<img src="assets/opencode_screenshot2.png" alt="OpenCode Agent 交互" width="600">

<img src="assets/wechat_screenshot2.jpg" alt="微信收到回复" width="400">

工具列表

工具	说明
login_qrcode	生成微信登录二维码
check_qrcode_status	检查二维码是否已扫码确认
logout	退出登录并清除凭证
get_messages	拉取新消息（wait=true 阻塞等待直到收到消息）
send_text_message	发送文本消息
send_typing	发送或取消"正在输入"状态

数据存储

所有数据保存在 ~/.mcp-wechat-server/ 目录下：

文件	说明
account.json	Bot Token 和用户 ID（权限 600）
state.json	消息游标和上下文 Token
qrcode.png	生成的二维码图片
qrcode.txt	生成的终端二维码文本

本地开发

git clone https://github.com/Howardzhangdqs/mcp-wechat-server.git
cd mcp-wechat-server
bun install
bun run dev

许可证

MIT