WeChat MCP macOS

macOS 微信本地数据读取。解密本地数据库，读取聊天记录、搜索、语音转文字、生成群聊总结。

零 API 调用，纯本地运行，不修改原始数据库。

架构

plugin/ + skill/                  ← Hana Agent 集成层
    ↓ 对话触发
prompts/render.py                 ← 匹配 chat → 取数 → 压缩上下文 → 生成给 LLM 的 JSON prompt
    ├── registry.json             ← 按群/联系人配置不同 prompt
    ├── templates/                ← LLM 模板文件
    └── summaries/                ← 生成的长图与中间产物
    ↓
scripts/group-summary-workflow.sh ← prepare / render 一键流水线
    ├── enrich_summary_json.py    ← 注入统计、热度、活跃群友、关键词 tag
    └── validate_summary_json.py  ← 渲染前自检
    ↓
backend/.venv/                    ← Python 运行时（wechat_mcp_macos 包）
    ├── pipeline.py               ← 纯规则总结 + 联系人解析
    ├── summary_img.py            ← 长图渲染
    └── voice_to_text.py          ← 语音转文字

contacts.json                    ← 从 contact.db 解密的通讯录（6000+ 条）
group_nicknames.json             ← 群成员补充昵称映射（fallback）

功能

能力	入口	原理
读取聊天记录	`wechat_read`	解密 SQLCipher 4 本地数据库直接查询
关键词搜索	`wechat_search`	跨群全文搜索，按发送者/时间分组
群聊列表	`wechat_groups`	列出所有微信群名称
纯规则总结	`pipeline.py`	零 LLM：活跃度/话题/时间线/热词
语音转文字	`voice_to_text.py`	SILK 解码 + faster-whisper
结构化管理 Prompt	`prompts/render.py`	registry 匹配 chat → 压缩上下文 → 生成给 LLM 的 JSON prompt
日期区间查询	`scripts/chat_query.py`	群聊/私聊、任意日期区间、双方身份和头像 wxid
总结流水线	`scripts/chat-summary-workflow.sh`	prepare / render 一键串联取数、enrich、自检、出图
长图渲染	`summary_img.py`	AI 总结 JSON + 统计增强数据 → Pillow 渲染为图片

快速开始

1. 克隆并创建环境

git clone https://github.com/yancongya/wechat-mcp-macos.git
cd wechat-mcp-macos

# 创建 Python 运行时环境
python3 -m venv backend/.venv

# 安装核心 Python 包
backend/.venv/bin/pip install wechat-mcp-macos

# 安装项目依赖
backend/.venv/bin/pip install -r requirements.txt

# 长图生成需要 Pillow
pip3 install Pillow --break-system-packages

2. 提取密钥

# 确保微信已登录，需要 sudo 权限
sudo backend/.venv/bin/python init-keys.py

3. 生成总结

默认日报口径：

hours=0 表示今天自然日 0:00 到现在
不再默认使用 rolling 24h，避免跨天和 token 膨胀
LLM 默认读取压缩上下文，不再直接吞全量原始聊天

# 统一切记用 backend/.venv/bin/python 执行
cd wechat-mcp-macos

# 纯规则总结（零 token）
backend/.venv/bin/python pipeline.py --dry-run --hours 24

# 指定群
backend/.venv/bin/python pipeline.py --dry-run --hours 24 --chat "琅泽"

# JSON 输出（供链式调用）
backend/.venv/bin/python pipeline.py --dry-run --hours 24 --json

# Prompt 渲染（匹配 registry → 填充 LLM 模板）
backend/.venv/bin/python prompts/render.py "琅泽群" --hours 48

# 日期区间查询（默认日界线 04:00，结束日期包含整天）
backend/.venv/bin/python scripts/chat_query.py "钟子鹏" \
  --start 2026-07-25 --end 2026-07-31

# 一键准备：群聊和私聊通用，取数 + 压缩上下文 + LLM JSON Prompt
bash scripts/chat-summary-workflow.sh prepare \
  --chat "钟子鹏" --start 2026-07-25 --end 2026-07-31

# 一键出图：render 自动 enrich + validate，再出图
bash scripts/chat-summary-workflow.sh render /path/to/summary.json

# 单独校验增强版 JSON
backend/.venv/bin/python scripts/validate_summary_json.py /path/to/summary.enriched.json

联系人解析

resolve_name() 三层 fallback，确保群聊总结中的发送者始终显示可读昵称：

contacts.json（通讯录，6000+ 条）— 从 contact.db 解密获得
group_nicknames.json（群成员补充映射）— 手动维护，用于通讯录中没有的群友
截断 wxid（兜底）— 如 wxid_psli7doelfml22 → psli7do

刷新通讯录

# 用现有密钥解密 contact.db 并更新 contacts.json
cd wechat-mcp-macos && python3 -c "
import json, os, sqlite3, sys
sys.path.insert(0, 'backend/.venv/lib/python3.14/site-packages')
from wechat_mcp_macos.decryptor import decrypt_database, decrypt_wal

with open('wechat_keys.json') as f:
    keys = json.load(f)
contact_db = os.path.expanduser('~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_hx1vuhtjkb3v22_1dd5/db_storage/contact/contact.db')
enc_key = keys.get('contact/contact.db')
cache = os.path.expanduser('~/.wechat-mcp/decrypted/contact/contact.db')
os.makedirs(os.path.dirname(cache), exist_ok=True)

decrypt_database(contact_db, cache, enc_key)
if os.path.exists(contact_db + '-wal'):
    decrypt_wal(contact_db + '-wal', cache, enc_key)

conn = sqlite3.connect(cache)
contacts = {}
for row in conn.execute('SELECT username, nick_name, remark FROM contact WHERE username != \"\"'):
    uname, nick, remark = row
    contacts[uname] = {'nickname': nick or '', 'remark': remark or ''}
conn.close()

with open('contacts.json', 'w') as f:
    json.dump(contacts, f, ensure_ascii=False, indent=2)
print(f'contacts.json updated: {len(contacts)} entries')
"

若密钥过期，需重新运行 sign_wechat.sh + extract_keys.sh。

项目结构

wechat-mcp-macos/
├── backend/
│   └── .venv/              # Python 运行时（wechat_mcp_macos 包）
├── plugin/                 # Hana 插件（manifest.json + 4 tools）
├── skill/                  # Hana Agent skill
├── prompts/                # Prompt 管理系统
│   ├── registry.json       # trigger 定义
│   ├── render.py           # 匹配引擎
│   ├── templates/          # LLM prompt 模板文件
│   └── summaries/          # 生成的长图（.gitignore）
├── pipeline.py             # 纯规则总结 + 联系人解析
├── summary_img.py          # 长图渲染
├── voice_to_text.py        # 语音转文字
├── contacts.json           # 通讯录映射（从 contact.db 解密）
├── group_nicknames.json    # 群成员补充昵称（fallback）
├── crypto/                 # 解密模块
├── scripts/                # 日期解析、区间查询、群聊/私聊总结流水线
└── .gitignore

Hana 集成

安装 Skill

cp -r skill ~/.hanako/skills/wechat-mcp-setup

安装 Plugin

cp -r plugin ~/.hanako/plugins/wechat-mcp

触发方式

在 Hana Agent 中可直接说：

"检查微信状态"
"列出所有微信群"
"读一下 xxx 的消息"
"搜一下关于 xxx 的内容"
"总结琅泽群"

插件通过 execFileSync + JSON stdin → scripts/plugin_bridge.py 调用仓库查询核心，避免字符串拼接与输入转义风险。

读取与搜索均支持：

date/start/end/today/yesterday/last/hours
默认 04:00 日界线
“我”与联系人/群成员身份识别
avatar_username 真实头像键
page_size + cursor 稳定分页，同一秒多条消息不会漏读

日报长图默认内容

当前 enrich + render 默认会在长图里补充：

标题下统计说明：原始文本字数、压缩后字数、约减少的 tokens 百分比
自适应热度曲线：单日/不超过 48 小时按小时，多日/周报按 04:00 逻辑日统计每天消息量
活跃群友头像 + 名字 + 消息数
关键词 tag
省流版（自动过滤技术指标行，避免与顶部统计说明重复）

渲染防裁切机制

summary_img.py 内置了内容安全保护：

预计算高度时预留 2x 安全余量，防止文字写出画布
渲染完成后根据实际内容定位自动裁切多余空白
若内容超出预计算范围，会自动扩展画布并补全纸张纹理

中间数据清理

cleanup-policy.json 同时控制时间与容量阈值。默认在每次 chat-summary-workflow.sh prepare 前执行：

# 只检查，不删除
backend/.venv/bin/python cleanup.py --check

# 正式清理
backend/.venv/bin/python cleanup.py

默认策略：总结中间文件保留 7 天/上限 50 MB，最终图片保留 30 天/上限 100 MB，解密缓存保留 7 天/上限 500 MB，日志保留 30 天/上限 50 MB；每类始终保护最新文件。配置不触碰密钥、MCP 配置或微信原始数据库。

Prompt Registry

按群/联系人自定义 prompt 模板，无需改代码。

{
  "prompts": [
    {
      "id": "langze-daily",
      "name": "琅泽群每日总结",
      "trigger": { "type": "group", "chats": ["58299288465@chatroom"] },
      "process": { "mode": "llm", "template_file": "group-summary-image-json.txt" },
      "output": { "text": true, "image": true }
    }
  ]
}

匹配优先级：精确匹配 → 类型回退（群/私聊）→ catchall。

决策规范

用户要数据 → 纯脚本返回结果
用户要分析 → 先脚本取数据，再 AI 理解
用户要总结/分析 → 区间取数 → AI 输出带 avatar_username 的 JSON → 默认生成图片
用户明确只要文字 → 才跳过图片
本人身份 → 展示名为“我”，真实 self wxid 用于消息统计和头像匹配
用户要发消息 → 生成文件，用户手动粘贴

零 token 优先。

依赖

macOS（Apple Silicon / Intel）
Python >= 3.10
Homebrew + sqlcipher + llvm
微信 for Mac（已登录过）

致谢

解密模块来自 wechat-digest (MIT)
密钥提取来自 wechat-db-decrypt-macos
MCP Server 来自 wechat-mcp-macos

License

MIT

Navigation Menu

Repository files navigation

WeChat MCP macOS

架构

功能

快速开始

1. 克隆并创建环境

2. 提取密钥

3. 生成总结

联系人解析

刷新通讯录

项目结构

Hana 集成

安装 Skill

安装 Plugin

触发方式

日报长图默认内容

渲染防裁切机制

中间数据清理

Prompt Registry

决策规范

依赖

致谢

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
crypto		crypto
plugin		plugin
prompts		prompts
scripts		scripts
skill		skill
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
cleanup-policy.json		cleanup-policy.json
cleanup.py		cleanup.py
contacts.example.json		contacts.example.json
cover.png		cover.png
extract-messages.py		extract-messages.py
feather.png		feather.png
group_nicknames.json		group_nicknames.json
init-keys.py		init-keys.py
pipeline.py		pipeline.py
requirements.txt		requirements.txt
server.py		server.py
summary_img.py		summary_img.py
voice_to_text.py		voice_to_text.py

Folders and files

Latest commit

History

Repository files navigation

WeChat MCP macOS

架构

功能

快速开始

1. 克隆并创建环境

2. 提取密钥

3. 生成总结

联系人解析

刷新通讯录

项目结构

Hana 集成

安装 Skill

安装 Plugin

触发方式

日报长图默认内容

渲染防裁切机制

中间数据清理

Prompt Registry

决策规范

依赖

致谢

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages