↗WeChat MCP开始使用 ↗
安装客户端工具示例排障

WeChat MCP

通过标准 MCP 协议，让 AI 客户端读取和操作 Windows 桌面微信。WeChat MCP 由本地 Windows 服务和 Python MCP 适配器组成。

适配器提供 13 个工具，覆盖会话查找、消息读取、图片获取、文本与文件发送，以及操作回执查询。聊天内容由你选择的 AI 客户端与模型处理。

环境与安装

  • Windows，已安装 .NET Framework 编译器。
  • Python 3.9+，可通过 python 命令启动。
  • 桌面微信已登录；操作期间保持 Windows 唤醒、解锁。
  • 支持本地 stdio MCP 的客户端。
当前发布状态
本页工具说明基于 2026-10-03 本地开发版本。公共仓库暂未包含 MCP 适配器，因此公开源码下载尚不能完成 MCP 安装。已有完整开发版本可从构建步骤继续；新用户需等待包含 mcp/server.py 与 V2 后端的版本发布。

1. 下载公共源码

在 PowerShell 中运行。该命令下载当前公共源码；下载后先核对 MCP 文件是否存在。

git clone https://github.com/aytoast/wechat-mcp.git
cd wechat-mcp
Test-Path .\mcp\server.py

如果返回 False，请等待包含 MCP 适配器的版本发布后再继续。

下载公共源码 ZIP ↗

2. 构建并启动本地服务

以下步骤适用于包含 MCP 与 V2 后端的完整源码。编译器默认路径为 C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe。

.\build.bat

构建完成后，打开 bin 文件夹并启动生成的程序。WeChat MCP 本地服务会驻留在系统托盘。API 使用 http://127.0.0.1:8081/wechat/。

3. 接入你的客户端

复制下方配置，并把示例路径换成实际源码目录。Python 适配器仅使用标准库，无需安装额外 Python 包。

客户端配置

1

配置完成后，重新连接客户端中的 MCP 服务，检查工具列表，并先调用 get_status。连接失败时先确认本地服务与 Python 路径。配置示例依据客户端 CLI 与标准 MCP 配置，其他客户端的实际运行仍需验证。

架构与数据流

AI 客户端
  → MCP stdio · Python 适配器
  → 本机 HTTP API · Bearer 认证
  → Windows UI Automation / Win32
  → 微信桌面窗口

认证 Token 由本地服务生成，MCP 适配器自动读取本地认证文件。不要把 Token 写入网页或客户端命令。

本地服务只接受本机连接。聊天读取与操作可能切换会话、滚动窗口或占用前台焦点。采集范围来自桌面 UI；AI 客户端返回给模型的数据受其自身配置和服务条款约束。

高级配置支持 --base-url 和 --token-file。使用默认安装时，保留内置配置即可。

历史、图片与游标

read_messages 按时间顺序返回结构化消息。将返回的 next_cursor 传入下一次调用的 before，继续读取更早历史。游标绑定会话与操作，15 分钟或服务重启后失效。

首次 poll_messages 默认建立基线；设置 include_initial: true 可以读取当前可见消息。后续传回 cursor 获取增量。出现 resync_required: true 时，重新读取历史。

图片默认随读取返回，每次最多 4 张、合计 6 MiB。存在 next_image_offset 时，用相同的 before 和 limit，把该值传入 image_offset 继续取图。检查图片可用状态及 page_fingerprint，再继续更早文本。

只有 poll_messages 返回可用于后续操作的 message_ref。引用在 5 分钟或服务重启后失效，界面变化也可能使其不可用。引用回复、转发和单张取图之前应重新轮询。

发送与操作回执

发送文本、文件、引用回复和转发都需要 request_id。调用方应先保存操作意图及 ID。同一 ID 与相同参数再次调用时返回原回执。复用 ID 却更改参数会被拒绝。ID 长度为 8–100，仅使用字母、数字、下划线和连字符。

检查回执中的 status。rejected 表示拒绝，outcome_unknown 表示结果未知。超时或重启后，使用原 ID 调用 get_command_status，不要自动更换 ID 重发。

observed_in_chat 只描述本地 UI 观察，delivery: "unverified" 表示接收端送达未验证。

工具参考

参数名称与 MCP 适配器保持一致。下面列出必填参数、常用可选参数和关键行为。

13 个工具

get_status

查看微信窗口、本地服务能力与当前状态。无必填参数，适合作为连接后的首次调用。

{}

list_chats

查找已观察到的桌面会话。可选：query、limit 1–1000、timeout_ms 1000–60000。可能滚动侧栏；展示名称不能作为稳定账号 ID。

{ "query": "设计", "limit": 20 }

get_chat

打开指定会话并核对标题。必填：chat_name。发现同名匹配歧义时拒绝操作。

{ "chat_name": "设计群" }

read_messages

读取聊天历史与可用图片。必填：chat_name。可选：limit 1–2000、before、include_images、image_offset 0–2000、max_pages 1–500、timeout_ms 1000–60000。

{ "chat_name": "设计群", "limit": 20, "include_images": true }

检查 stop_reason、continuation 与 reached_history_start。桌面历史顶部不代表手机历史已全部同步。

poll_messages

获取基线后的消息。必填：chat_name。可选：cursor、include_initial、include_images。调用会执行 UI 操作；轮询频率由客户端负责。

{ "chat_name": "设计群", "include_initial": true }

send_message

发送文本。每次新发送请生成并保存独立的 request_id，下面的 ID 仅供示例。必填：chat_name、text 1–4000 字符、request_id。保留现有草稿，并返回持久化回执。

{ "chat_name": "文件传输助手", "text": "MCP 连接测试", "request_id": "demo-send-0001" }

send_file

发送本地文件。必填：chat_name、file_path、sha256、request_id。使用绝对 Windows 路径，SHA-256 为目标文件实际摘要。文件最大 100 MiB。

用 Get-FileHash -Algorithm SHA256 计算摘要。服务不接受 UNC、设备路径或重解析点，不自动重试发送。

reply_message

引用指定消息并回复。必填：chat_name、message_ref、text、request_id。先调用 poll_messages 获得当前消息引用，使用返回值，保留原聊天界面。

forward_message

转发指定消息到一个目标会话。必填：chat_name、message_ref、target_chat、request_id。接收方必须经过可见界面核对。

get_chat_info

读取可见聊天资料、群成员标签和部分个人资料。必填：chat_name。返回资料来自 UI 观察，成员列表可能不完整。

{ "chat_name": "设计群" }

get_group_members

通过聊天记录成员筛选读取群成员。必填：chat_name。可选：limit 1–10000、timeout_ms 1000–60000、max_steps 1–20000。检查 complete 与 stop_reason；同名成员按观察结果保留。

{ "chat_name": "设计群", "limit": 100 }

get_message_image

获取消息图片并返回 MCP 图片内容。必填：chat_name、message_ref。可选：variant，默认 file 使用微信另存为；preview 返回含 UI 的可见消息行截图。请先轮询获取当前引用。

get_command_status

查询已保存的发送回执，无需再次提交。必填：request_id。

{ "request_id": "demo-send-0001" }

使用示例

以下为可交给 AI 客户端的指令示例。会话名称请换成自己的实际名称，摘要由客户端模型完成。

整理会话

读取设计群最近 30 条消息，整理已确定的事项和仍待确认的问题。
为每条结论保留对应的原始消息。

查看图片

读取设计群最近的消息和可用图片，说明设计稿中有哪些变化。
如果图片无法获取，告诉我哪些内容没有读到。

验证发送

向文件传输助手发送「MCP 连接测试」。
保存 request_id，并查询操作回执。

常见问题与排障

找不到 Python 或适配器

运行 python --version 检查版本，确认配置中的 server.py 为存在的绝对路径。下载的公共源码缺少该文件时，等待 MCP 版本发布。

服务无法连接

检查托盘进程是否启动，8081 端口是否被其他程序占用，微信是否登录并处于解锁桌面。MCP 接入进程需与微信服务位于同一台 Windows 电脑。

认证失败

确认服务已经生成 Token 文件，适配器使用相同 Windows 用户运行。使用自定义 Token 路径时，通过 --token-file 指定。

会话不明确或引用过期

核对完整会话名称。执行 poll_messages 获取当前消息引用；同名会话、界面变化或引用失效时，不通过文本猜测目标。

锁屏、历史缺口与未知回执

解锁桌面后重新读取。遇到历史缺口应重新同步，遇到未知发送结果应查询原回执。历史覆盖、操作提交和对方送达是独立状态。

版本与验证范围

文档核对日期：2026-10-03。工具与参数依据本地 MCP 适配器和 Core API V2 文档。已有 stdio 初始化、工具发现及连接已部署服务的状态查询验证记录；各客户端的完整安装流程尚未逐一验证。

项目源码位于 aytoast/wechat-mcp。当前公共源码与本页描述的本地开发版本存在差异。新用户安装需要包含 MCP 适配器与 V2 后端的公开版本。

WeChat MCP 为独立社区项目，与腾讯及微信团队无隶属关系。