WeChat Local Agent MCP
This MCP server offers read-only, local-first access to WeChat chat history, with search, timeline browsing, and opt-in media/link/voice enrichment.
Readiness & identity-free status –
statuschecks live-read readiness and enabled enrichment options without exposing identity paths.Session listing & resolution –
sessionslists chats with filtering by type/keyword;resolve_chatmaps a display name to a stable talker/group.Message search –
searchfinds messages by keyword, with optional chat, sender, type, time range, and snippet-only mode.Timeline & range reading –
timeline,read_chat_range, andread_chat_dayread bounded pages with cursor pagination and compact output;read_multiple_chats_dayreads per-chat pages for the same day.Counting & unread –
count_messagescounts messages in a period without returning bodies;unreadlists unread sessions (filterable by group/private).Incremental events –
read_eventsfetches event batches for incremental sync (no send/UI control).Group awareness –
group_memberslists members and nicknames for a resolved group, with optional stats.Context & details –
contextreads bounded messages around a specific anchor;message_detailsexpands a single message including safe quotes/forwards/links.Media & enrichment (opt-in) –
message_mediareturns local media paths;ocr_message_imagesOCRs images;extract_message_filesextracts text from files;fetch_message_linksfetches public HTTPS links;transcribe_message_voicetranscribes voice via a local transcriber. All require explicit environment flags (e.g.,WECHAT_MCP_ENABLE_MEDIA).Privacy-first design – All operations are read-only, local, and never send chat content to the cloud; only stdio transport is used.
Provides local-first, read-only access to the owner's WeChat chat history, enabling search, summarization, day/range pagination, unread and event queries, group member lists, and structured message details, with optional gated enrichment for media, OCR, files, voice, and links.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WeChat Local Agent MCP Summarize yesterday's messages from the 'Project' group chat."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
微信本地聊天记录 MCP
请先理解数据边界。 本项目不会主动上传微信数据库或数据库密钥,但 MCP 返回给 Agent 的所选消息、图片、附件、语音转写和链接正文,会进入 Agent 主机的模型上下文。如果 Agent 使用云端模型,这些内容可能被发送给对应的模型 提供商。
不要通过 API 中转、第三方代理、聚合路由、共享网关或来源不明的 OpenAI 兼容接口使用本项目。 中转服务可能记录、缓存或保留聊天内容,而本项目无法 审计或控制其数据处理方式。本项目仅推荐与完全在本机运行的推理模型配合 使用,使消息内容不离开设备。使用任何云端模型前,请自行确认提供商的数据 政策,并视为聊天内容可能离开本机。
这是一个本地优先、仅使用 stdio 的只读 MCP,让 Agent 查询和总结电脑所有者 自己的微信聊天记录。它支持稳定的日期与时间范围分页、批量群聊工作流、未读与 增量事件查询、上下文、结构化消息详情、按需媒体地址,以及受显式开关控制的 OCR、附件文本、语音转写和链接抓取。
本项目是独立社区项目,与腾讯或微信没有隶属或背书关系。仅可访问你本人拥有或 已获得明确授权的数据,并遵守当地法律及适用条款。
隐私建议
即使使用本机模型,也应遵循最小化原则:
先限定聊天、日期、时间范围和关键词,不要无目的地读取全部历史。
先用
count_messages估算规模,再以compact=true分页读取。大群聊逐页总结,只把与当前问题相关的摘要保留在模型上下文中。
不需要身份追踪时,不在报告中保留账号 ID、数据库路径或其他稳定标识。
图片和表情只返回轻量引用;仅让 Agent 打开与当前问题有关的单张图片。
表情默认为低优先级,除非用户明确询问,或缺少表情就无法理解语义,否则跳过。
OCR、附件全文、语音转写、媒体派生写入和网络抓取只在确有需要时开启。
不要把数据库、密钥、原始聊天导出、解码媒体或运行日志上传到 Issue、PR、网盘 或其他外部服务。
Related MCP server: wbot
让 Agent 安装
可以把下面的指令交给具备本机安装能力的 Agent:
克隆 https://github.com/hetiankong/wechat-local-agent-mcp,完整阅读
AGENTS.md,并按其中流程安装和验证本地只读微信 MCP。安装期间不要输出
数据库密钥、账号标识或消息内容。AGENTS.md 是完整的安装决策树、安全合同、验证清单、排障指南和大群聊读取
流程。
macOS Apple Silicon
git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
./scripts/install.sh --register-codex
./scripts/bootstrap-macos.shWindows 11 amd64
git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
.\scripts\install.ps1 -RegisterCodex安装器会下载官方 r266-tech/wechat-cli 运行包,并校验发布方提供的 .sha256
配套校验文件;校验不通过时会直接停止。本仓库不包含微信数据库、密钥、解码媒体、
消息或账号标识。离线环境可以通过 WECHAT_CLI_RELEASE_ZIP 和
WECHAT_CLI_RELEASE_SHA256 提供运行包及校验文件,校验要求不会因此降低。
核心工具
resolve_chat、sessions、search、timelineread_chat_day、read_chat_range、read_multiple_chats_daycount_messages、unread、read_events、group_memberscontext、message_details、message_media
以下工具默认受独立开关控制:
ocr_message_imagesextract_message_filestranscribe_message_voicefetch_message_links
普通紧凑读取不会返回媒体路径、二进制负载、base64 或调试与密钥字段。
按需读取媒体
紧凑时间线使用轻量 media_ref 区分图片和表情:
图片为普通优先级,仅在与用户问题相关时调用
message_media。表情为低优先级,默认不加载、不派生、不重复尝试。
message_media每次最多返回八个经过白名单验证的本地文件地址。图片字节和 base64 不会进入普通聊天分页结果,因此不会提前消耗图片 Token。
选中的加密图片需要生成本地可读副本时,可调用:
message_media(..., allow_derived_write=true)此操作要求操作者预先启用 WECHAT_MCP_ENABLE_DERIVED_WRITES=1,并且只应对
已选中的单条图片消息调用一次。它可能创建私有解码缓存,但不会修改微信数据库。
OCR 仍需单独开启。
读取大群聊
例如读取某个群今天的全部消息,可以告诉 Agent:
读取“项目群”今天的全部消息。先 resolve_chat 和 count_messages,再循环
read_chat_day(limit=200),每次使用 next_cursor,直到 done=true。逐页总结后按
时间顺序合并,重要结论保留消息 ID、发送者和时间。图片只在与结论相关时按需读取,
表情默认跳过。九百条消息通常需要约五次有界 MCP 调用。不要只读第一页,也不要在一次工具调用中
请求全部消息。period 支持 today/今天、yesterday/昨天、
this_week/本周、last_week/上周、最近若干小时或任意 YYYY-MM-DD。
安全边界
微信源数据库始终以只读方式打开。
核心子进程使用参数数组、
shell=False、关闭的标准输入、超时、输出上限和命令 白名单。只有单独启用派生写入时,选中的媒体才可能生成私有本地缓存文件。
紧凑时间线只携带媒体提示;
message_media按需返回数量受限的本地地址。MCP 不提供通用 SQL、通用命令执行、导出、发送或回复消息、微信界面控制及无限 监听功能。
MCP 只允许本地 stdio,不得暴露为 HTTP 或 SSE 服务。
macOS 初始化保持 SIP 开启,并使用受管理的影子微信,不重新签名已安装的原版 微信。
经过审阅的
wxkey补丁不会接收或保存管理员密码;认证由 macOS 系统窗口处理。链接联网抓取默认关闭,并限制凭据、私有 IP、不安全跳转、非文本内容和过大响应。
安全问题及数据处理细节见 SECURITY.md。
本地开发
python3 -m venv .venv
.venv/bin/python -m pip install -e . pytest
.venv/bin/python -m pytest -qPython 单元测试和安全测试不需要真实微信数据。涉及真实数据的验收只能输出计数、 布尔值和字段名,不得输出账号标识、聊天名称、消息正文、数据库路径或密钥。
致谢
本项目的查询运行时和密钥初始化建立在
r266-tech/wechat-cli 与
r266-tech/wxkey 的工作之上。架构还参考了:
许可证和第三方组件的准确使用范围见 THIRD_PARTY_NOTICES.md。
Available Tools
19 toolscontextB
Read bounded context around exactly one stable message anchor.
Inputs: chat (required), local_id, after_count, before_count, +3 more. Returns: object
count_messagesB
Count a bounded period without returning bodies; scans stable 200-message pages.
Inputs: chat, period, talker, timezone, +1 more. Returns: object
extract_message_filesA
Extract text from local txt/PDF/Office files; explicit MEDIA and FILE_TEXT opt-in required.
Inputs: chat (required), local_id, server_id_str, max_chars_per_file. Returns: object
fetch_message_linksB
Fetch public HTTPS links referenced by one message; explicit NETWORK opt-in required.
Inputs: chat (required), local_id, server_id_str, max_chars_per_link. Returns: object
group_membersB
List group members and group nicknames for a resolved group chat.
Inputs: chat (required), limit, offset, include_stats. Returns: object
message_detailsB
Expand one message, including safe quote/forward/link/file structures without debug secrets.
Inputs: chat (required), local_id, server_id_str. Returns: object
message_mediaC
Locate existing local message media paths; requires WECHAT_MCP_ENABLE_MEDIA=1.
Inputs: chat (required), local_id, server_id_str, allow_derived_write. Returns: object
ocr_message_imagesC
OCR readable local images with macOS Vision; explicit MEDIA and OCR opt-in required.
Inputs: chat (required), local_id, languages, server_id_str, +1 more. Returns: object
read_chat_dayB
Read one page for a day/natural period; loop with next_cursor until data.page.done.
Inputs: chat, limit, cursor, period, +4 more. Returns: object
read_chat_rangeA
Read one stable page inside an explicit [after,before) range; reuse next_cursor.
Inputs: after (required), before (required), chat, limit, +4 more. Returns: object
read_eventsA
Read one incremental event batch; no follow loop, sending, or UI control.
Inputs: chat, limit, cursor, talker, +2 more. Returns: object
read_multiple_chats_dayA
Read one page per chat for the same day; continue each chat with returned cursors.
Inputs: chats (required), period, compact, timezone, +2 more. Returns: object
resolve_chatC
Resolve a display name to a stable talker; prefer type_filter=group when applicable.
Inputs: query (required), limit, type_filter. Returns: object
searchB
Search local messages with optional chat, sender, type, and half-open time range.
Inputs: keyword (required), chat, after, limit, +7 more. Returns: object
sessionsB
List sessions; use type_filter=group for group-chat workflows.
Inputs: limit, offset, keyword, type_filter. Returns: object
statusB
Check live-read readiness and opt-in enrichment capabilities without identity paths.
Inputs: no named parameters. Returns: object
timelineA
Read one bounded timeline page; loop with data.page.next_cursor until done.
Inputs: chat, after, limit, order, +10 more. Returns: object
transcribe_message_voiceA
Transcribe a local voice file using a user-configured argv-only local transcriber.
Inputs: chat (required), local_id, server_id_str, allow_derived_write. Returns: object
unreadB
List unread sessions, optionally restricted to group/private chats.
Inputs: limit, offset, type_filter. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clear, distinct purposes, especially the specialized enrichment tools (OCR, file extraction, voice transcription). The four message-reading tools (timeline, read_chat_range, read_chat_day, read_multiple_chats_day) are similar but their range semantics and usage patterns differ enough that descriptions should guide correct selection.
The majority of tools use a verb_noun pattern (read_chat_range, count_messages, resolve_chat), but a few single-word noun-style names (timeline, unread, context, status, sessions, search) and noun_noun names (message_details, message_media) break the pattern. The inconsistency is noticeable but not chaotic.
At 19 tools, the surface is on the heavier side but still scoped to a single domain (local WeChat data access). Each tool addresses a concrete feature, though some could potentially be merged (e.g., the reading paging tools), making the count borderline.
The tool set covers a comprehensive range of read-only operations: browsing, searching, counting, unread sessions, incremental events, context expansion, message details, and multiple enrichment capabilities (media, OCR, file text, links, voice). It lacks sending or UI control, which appears intentionally out of scope, leaving no major functional gaps for a local agent.
Maintenance
Related MCP Connectors
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- FlicenseCqualityDmaintenanceMCP server for reading local WeChat data, enabling AI assistants to query chat history, contacts, sessions, and more via MCP tools.209-
- AlicenseNot gradedqualityBmaintenanceMCP server providing an Agent-first, read-only interface to authorized WeChat conversations, with CLI and plugin support for Codex and Claude Code.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query local WeChat chat data through read-only MCP tools, including sessions, messages, contacts, search, and statistics, with everything processed locally.63 PyPI6MIT
- AlicenseNot gradedqualityBmaintenanceAn unofficial experimental local MCP server that lets AI clients work with an already logged-in Windows Weixin desktop client, providing bounded conversation and message reads, group and message search, polling of up to 16 selected chats, guarded text and attachment submission, and image/file viewing handoffs. It also exposes hybrid Computer Use prompts for native mention handoffs, while remeasuring the window, DPI, and target controls on each action and failing closed when evidence is insufficient.1Apache 2.0