{"id":50417822,"url":"https://github.com/r266-tech/wechat-cli","last_synced_at":"2026-05-31T07:01:54.457Z","repository":{"id":351759200,"uuid":"1212371914","full_name":"r266-tech/wechat-cli","owner":"r266-tech","description":"WeChat/微信 local chat history MCP server for macOS agents. Read messages, contacts, media, favorites, transfers, red packets, Moments and full-text search from local WeChat 4.x data.","archived":false,"fork":false,"pushed_at":"2026-05-31T05:24:29.000Z","size":755,"stargazers_count":42,"open_issues_count":4,"forks_count":14,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T06:19:41.030Z","etag":null,"topics":["agents","ai-agents","chat-history","claude-code","codex","golang","local-data","local-first","macos","mcp","mcp-server","model-context-protocol","wcdb","wechat","wechat-data","wechat-mcp","weixin"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r266-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-16T10:07:15.000Z","updated_at":"2026-05-31T05:24:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/r266-tech/wechat-cli","commit_stats":null,"previous_names":["r266-tech/wx-mcp","r266-tech/wechat-local-mcp","r266-tech/wechat-cli"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/r266-tech/wechat-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r266-tech%2Fwechat-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r266-tech%2Fwechat-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r266-tech%2Fwechat-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r266-tech%2Fwechat-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r266-tech","download_url":"https://codeload.github.com/r266-tech/wechat-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r266-tech%2Fwechat-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33722156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-agents","chat-history","claude-code","codex","golang","local-data","local-first","macos","mcp","mcp-server","model-context-protocol","wcdb","wechat","wechat-data","wechat-mcp","weixin"],"created_at":"2026-05-31T07:01:53.159Z","updated_at":"2026-05-31T07:01:54.450Z","avatar_url":"https://github.com/r266-tech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wechat-cli\n\n本机微信数据 CLI。给强 agent 用，也给人直接用。\n\nmacOS / Windows · 本地解密 · 一行安装 · 稳定 JSON · 聊天记录 / 搜索 / 图片 / 文件 / 语音转写 / 朋友圈 / 转账红包\n\n`wechat-cli` 读取你电脑上的 WeChat / 微信 4.x 本地数据库，把消息、联系人、群聊、媒体、朋友圈、收藏、转账、红包等数据输出成结构化 JSON。数据默认留在本机，不上传到云端。\n\n它不是微信机器人，不控制屏幕，不发消息，不自动点赞评论，也不是公众号或小程序工具。\n\n## 安装\n\nmacOS:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/r266-tech/wechat-cli/main/scripts/install-release.sh | zsh\n```\n\nWindows:\n\n```powershell\npowershell -NoProfile -ExecutionPolicy Bypass -Command \"irm https://raw.githubusercontent.com/r266-tech/wechat-cli/main/scripts/install-release.ps1 | iex\"\n```\n\n默认安装的是 CLI，不注册 MCP，不装后台 watcher。安装完成后命令会放到用户 PATH 上：\n\n- macOS: `~/.local/bin/wechat-cli`\n- Windows: `%LOCALAPPDATA%\\Microsoft\\WindowsApps\\wechat-cli.cmd`，如该目录不存在则使用 `%USERPROFILE%\\.local\\bin\\wechat-cli.cmd`\n\n首次安装前请确认：\n\n- macOS arm64 + WeChat 4.x，或 Windows amd64 + Windows WeChat / Weixin 4.x\n- 微信已登录，并至少打开过一个聊天\n- macOS 首次 key 初始化可能要求输入一次 Mac admin 密码；密码只输入到本机隐藏提示，不要发给 agent 或网页。密码会存入用户 Keychain，供后续本机 key refresh 使用；安装器也可能临时启动一个 wechat-cli 管理的 WeChat shadow copy 来完成 no-SIP 初始化\n- macOS 15+ 建议安装后把 `~/.local/share/wechat-cli/wechat-cli` 和 `~/.local/share/wechat-cli/wxkey` 加到 Full Disk Access，减少系统隐私弹窗\n\n## 更新\n\n安装过 release 版后，直接运行：\n\n```bash\nwechat-cli update\n```\n\n这个命令会下载 GitHub latest release zip、校验 sha256，然后用包内 installer 覆盖安装。macOS 会等待更新完成并返回 JSON；Windows 会先启动后台 updater 再退出，因为 Windows 不能覆盖正在运行的 `.exe`，返回 JSON 里的 `data.log` 是后台更新日志。agent 更新完后跑一次：\n\n```bash\nwechat-cli sessions\n```\n\n老版本还没有 `update` 命令时，重新运行上面的安装一行命令也会覆盖升级；agent 场景可在 macOS 上用 `curl -fsSL https://raw.githubusercontent.com/r266-tech/wechat-cli/main/scripts/install-release.sh | zsh -s -- --update`。\n\n## 快速开始\n\n```bash\nwechat-cli sessions\nwechat-cli resolve-chat \"张三\"\nwechat-cli timeline \"某个群\" --limit 20\nwechat-cli history \"张三\" --view agent --limit 50\nwechat-cli search \"关键词\" --in \"某个群\"\nwechat-cli media \"某个群\" --type image --limit 10\n```\n\n所有命令面向 agent，stdout 默认输出紧凑 JSON；成功统一返回\n`{\"ok\":true,\"tool\":\"...\",\"command\":\"...\",\"data\":...}`，失败返回\n`{\"ok\":false,\"error\":...}`。`--json` 可传但只是兼容 no-op，人工查看时用\n`--pretty`。常用命令是薄封装，完整能力都可以通过通用调用访问：\n\n```bash\nwechat-cli timeline \"某个群\" --limit 20 --pretty\nwechat-cli timeline --help\nwechat-cli tool-schema chat_timeline\nwechat-cli tools\nwechat-cli call chat_timeline --chat \"某个群\" --limit 20\nwechat-cli call-json messages '{\"chat\":\"张三\",\"limit\":50,\"view\":\"agent\"}'\nprintf '{\"keyword\":\"会议\",\"limit\":20}' | wechat-cli call-json search\n```\n\n`timeline --help` / `tool-schema \u003ccommand-or-tool\u003e` 也返回同一个成功 envelope，\n`data.agent` 里包含 agent 示例、分页策略和常见恢复动作。默认 `images[]` 只暴露\n一个最佳可读本地路径：有原图/高清图就返回原图/高清图，只有拿不到时才回落到缩略图。\n`export` 默认 `view=agent`，JSONL 每行与 timeline message 行同形；需要底层字段时传\n`--view raw`。合并转发里的图片会尽量解析到 `forward_chat.items[].images[].path`；\n只有拿不到来源资源或本地文件不可读时才保留 `forward_image_not_resolved`。\n\n`freshness` 是返回数据的新鲜度/诊断信息：例如是否触发过 metadata 自动刷新、分页是否还有下一页、结果是否可能受缺 key 或 cache 滞后影响。\n\n## 常用命令\n\n| 命令 | 用途 |\n| --- | --- |\n| `update` | 更新到 GitHub latest release |\n| `sessions` | 最近会话、未读数、最后消息摘要 |\n| `resolve-chat` | 把昵称、备注、群名解析成稳定 talker |\n| `timeline` | 普通读聊天的首选入口，返回 `query` / `freshness` / `messages` |\n| `history` | 更底层的消息读取，支持时间、类型、sender、分页等过滤 |\n| `search` | 走微信本地 FTS 的跨会话全文搜索 |\n| `media` | 按消息定位图片、视频、文件等本机可读资源 |\n| `members` | 群成员、群名片、好友关系 |\n| `sns-feed` / `sns-search` / `sns-notifications` | 朋友圈时间线、搜索、点赞评论通知 |\n| `transfers` / `red-packets` | 转账和红包记录 |\n| `favorites` | 微信收藏 |\n| `export` | 单个会话导出到 jsonl / markdown / html |\n| `schema` / `sql` | 只读数据库结构和 SQL 诊断 |\n| `cache status` / `cache refresh` | metadata cache 诊断与刷新 |\n\n典型消息行：\n\n```json\n{\n  \"id\": {\"local_id\": 123, \"server_id_str\": \"9876543210\", \"talker\": \"xxx@chatroom\"},\n  \"time_iso\": \"2026-05-26T13:00:00+08:00\",\n  \"sender\": \"张三\",\n  \"sender_wxid\": \"wxid_xxx\",\n  \"is_from_me\": false,\n  \"kind\": \"image\",\n  \"text\": \"[图片]\",\n  \"images\": [{\"path\": \"/Users/me/.wechat-cli/media-cache/xxx.jpg\"}],\n  \"warnings\": []\n}\n```\n\n默认输出只给 agent 可用的信息：可读图片/视频/文件路径、链接、引用、转账红包、位置、语音转写等。raw XML、CDN/aeskey、不可读 `.dat`、候选路径和解码细节默认隐藏；维护者需要时再传 `include_debug=true` 或 `fields=full`。\n\n## MCP 兼容\n\n默认形态是 CLI。MCP 只保留为兼容入口：\n\n```bash\nwechat-cli serve-mcp\n```\n\n安装时需要 MCP 注册才加参数：\n\n```bash\n./install.sh --all --yes --mcp\npowershell -NoProfile -ExecutionPolicy Bypass -File .\\install.ps1 -All -Yes -Mcp\n```\n\n## 数据与隐私\n\n- `wechat-cli` 只读打开微信本地数据库。\n- 聊天正文默认 live read，不做全量正文 cache。\n- 联系人和会话 metadata cache 位于 `~/.wechat-cli/cache/`，用于名称解析和会话排序。\n- key map 位于 `~/.config/wxcli/config.json`。不要把它、微信 DB、聊天导出、截图或日志贴到公开 issue。\n- macOS sudo 凭据只保存在本机 Keychain；需要清除时用安装器的 `--clear-state` 或 `--uninstall --purge-state`，不要手工删散落文件。\n- `wechat-cli` 不发送消息、不自动转发、不点赞评论、不修改微信数据。\n\n## 排障\n\n| 现象 | 处理 |\n| --- | --- |\n| 找不到会话 | 先用 `wechat-cli resolve-chat \"名字\"` 看候选，必要时在微信里打开对应聊天后重试 |\n| 提示缺 key | 确认微信已登录并打开过聊天；macOS agent 可跑 `wxkey doctor` / `wxkey setup` |\n| 首次安装卡在 key scan | 新版会超时返回 `blocked_by=key_scan_timeout`，不会无限挂住；保持微信打开后重跑安装 |\n| macOS 频繁弹隐私授权 | 给 `wechat-cli` 和 `wxkey` 加 Full Disk Access |\n| 图片只有 warning 没 path | 微信本地只有 `.dat` 且 image key 仍不可用；打开原图或对应聊天后重试 |\n| Windows 初始化失败 | 确认 Windows 微信登录、`WECHAT_CLI_DB_ROOT` 指向直接包含 `db_storage` 的账号目录；极慢机器可设 `WECHAT_CLI_KEY_SCAN_TIMEOUT=5m` 后重试 |\n\n更详细的 agent 操作说明见 [AGENTS.md](AGENTS.md)，模型发现摘要见 [llms.txt](llms.txt)。\n\n## 开发\n\n```bash\ngo test ./...\ngo build -trimpath -o wechat-cli ./cmd/wechat-cli\n```\n\nmacOS release 包：\n\n```bash\nWECHAT_CLI_WCDB_DYLIB=/path/to/libWCDB.dylib ./scripts/package.sh 1.6.6\n```\n\nWindows release 包由 GitHub Actions 的 `Windows Release Package` workflow 构建。\n\n## 相关项目\n\n- [wxkey](https://github.com/r266-tech/wxkey): macOS WeChat key bootstrap companion，release 包内已包含，普通用户通常不需要单独安装。\n- [jackwener/wx-cli](https://github.com/jackwener/wx-cli): 面向终端/脚本的 WeChat data CLI，命令体验值得参考。\n- [joeseesun/wechat-radar](https://github.com/joeseesun/wechat-radar): 基于微信数据的本地情报看板。\n- [ylytdeng/wechat-decrypt](https://github.com/ylytdeng/wechat-decrypt): 微信数据库解密与导出工具集。\n\n## License\n\nSee [LICENSE](LICENSE).\n\n---\n\n\u003c!-- babata-star-callout-v2 --\u003e\n## If this saved you time\n\nStarring the repo helps prioritize which integrations stay maintained. This project is part of [babata](https://github.com/r266-tech).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr266-tech%2Fwechat-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr266-tech%2Fwechat-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr266-tech%2Fwechat-cli/lists"}