Skip to main content
Glama
mac-wechat-mcp

mac-wechat-mcp

by 849860605

mac-wechat-mcp

一个面向 macOS 个人微信的独立 MCP 项目。通过本机截图与 Apple Vision OCR,把当前指定会话的视觉上下文提供给支持 MCP 的 AI 客户端。

English · 客户端配置 · 本机校准 · 路线图

v0.1 是只读观察与回复草稿原型,尚不能自动发送微信。 标准 MCP 握手、图片返回和观察状态已通过合成数据测试;真实微信 4.1.13 的 OCR、身份核对、发送者识别与发送回读尚未完成验证。不要将本版本用于无人值守自动回复。

已实现

  • 标准 MCP stdio 接口,使用官方 Python SDK,不依赖任何已有微信 MCP。

  • 本机 Apple Vision OCR;返回聊天区域图片与原始 OCR 块。

  • 单个本地配置的联系人;目标标题不符、窗口移动/缩放、捕获失败时暂停。

  • 首次捕获仅建立基线,默认观察期限 10 分钟、最小轮询间隔 15 秒。

  • 前后画面对比;未处理的观察保留同一个 ID,连续变化保留最早未处理画面。

  • 回复草稿预览:只返回文字,不写入输入框、不发送消息。

  • 合成数据 demo,可在不启动微信、不授权屏幕录制的情况下测试 MCP 客户端。

Related MCP server: wechat-msg-mcp

能力边界

项目

当前状态

MCP stdio、工具发现、图片返回

已用 SDK 客户端测试

基线、过期、暂停、观察确认

已做自动化测试

真实 Mac 窗口截图与 OCR

已实现,待本机校准及实机验收

识别消息发送者、媒体类型、新消息

尚未可靠实现;OCR 一律标为 unknown

语义隐私过滤

客户端职责,服务端尚无语义过滤器

自动发送及发送确认

未开放

后台定时监听

无;由 MCP 客户端主动轮询

画面变化不等于收到新消息。 自己发消息、时间标签、滚动、图片加载都可能改变画面。观察 ID 不是微信消息 ID,不能承诺消息级 exactly-once。

快速运行 demo

需要 Python 3.11+ 和 uv。

git clone https://github.com/849860605/mac-wechat-mcp.git
cd mac-wechat-mcp
uv run mac-wechat-mcp --demo

这是 stdio 服务,会等待 MCP 客户端输入。终端不打印欢迎横幅是正常现象,日志写到 stderr。

通用客户端配置:

{
  "mcpServers": {
    "mac-wechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/mac-wechat-mcp", "run", "mac-wechat-mcp", "--demo"]
    }
  }
}

Claude Desktop、Cursor 等客户端通常接受此类配置,但实际入口请以各客户端文档为准。客户端必须支持 本地 stdio MCP 和图片工具结果,才能完成视觉复核;没有宣称已逐个验证这些客户端。纯云端客户端不能直接运行你 Mac 上的 stdio 进程。

接入真实微信

先阅读 校准说明,生成自己的本地配置。示例坐标不能直接当成已验证配置。

uv run --extra macos mac-wechat-mcp --config /absolute/path/config.local.json --doctor
uv run --extra macos mac-wechat-mcp --config /absolute/path/config.local.json

第一版使用 Python + PyObjC 调用 macOS 原生 API,便于安装与 MCP 集成;不需要运行 Swift 编译工具。微信须处于前台、可见、已登录,电脑须保持解锁。

工具

工具

行为

get_status

查看后端、到期时间及限制

start_observation

建立新基线;默认 600 秒、15 秒间隔

poll_changes

到达间隔后捕获;返回前后图片及 OCR

preview_reply

返回未发送草稿,不操作微信

acknowledge_observation

确认观察结果;uncertain 会暂停

pause_observation

暂停并使待处理草稿失效

demo_advance

仅 demo:改变合成画面

AI 客户端负责生成回复;项目不内置模型、不要求模型 API Key,也不自动调用外部模型服务。

数据与权限

  • 本机 OCR 不需要网络请求。MCP 返回的图片、文字会交给接入的 AI 客户端,可能进一步发往该客户端的模型服务商。

  • 仅返回校准的消息区域,标题用于本机核对。捕获时临时生成完整微信窗口 PNG,正常结束后删除;异常终止时操作系统临时目录中可能留下文件。

  • 不读取微信数据库,不上传联系人清单,不提供任意文件读取、Shell、浏览器或跨会话操作工具。

  • 不持久化聊天内容;当前会话的少量前后图片保留在进程内存中。

  • 备注名不能证明唯一身份。启用前须由使用者核对联系人资料;本版本不声称能自动解决同名联系人。

  • 不在仓库提交真实截图、聊天内容、本地配置、密钥、运行日志。

开发与验证

uv sync --extra macos  # 非 macOS 可省略 --extra macos
PYTHONPATH=src uv run python -m unittest discover -s tests -v

本机已通过 21 项状态/协议测试,以及 1 项 Apple Vision 合成图片 OCR 测试;wheel 和源码包构建成功。原生 OCR 测试需允许系统 Vision 运行,受限沙箱中可能失败。

测试包含真实 stdio 子进程握手、工具调用与 PNG 返回,但微信画面由 demo 合成,不是微信实机收发测试。

架构:server.py 定义 MCP 接口;core.py 管理观察生命周期;macos.py 负责窗口截图与 OCR;demo.py 提供无微信测试后端。

License

MIT。独立第三方项目,与腾讯/微信无隶属关系。

Available Tools

7 tools
acknowledge_observationA

Acknowledge client review: no_new_incoming_text, privacy_skip, reviewed, or uncertain.

uncertain pauses the session. This records review only, never a send receipt.

Inputs: outcome (required), session_id (required), observation_id (required).

demo_advanceA

DEMO ONLY: change the synthetic image, without accessing WeChat.

Inputs: no named parameters.

get_statusA
Read-only

Report backend availability, observation expiry and explicit sending limitations.

Inputs: no named parameters.

pause_observationA

Pause the current session and invalidate pending drafts. Restart creates a new baseline.

Inputs: no named parameters.

poll_changesA

Return pending before/after chat images and raw OCR after the polling interval.

A visual change can be a timestamp, own message, media or scrolling. It is not proof of a new incoming message. Repeated polls retain the pending observation ID.

Inputs: session_id (required).

preview_replyA
Read-only

Return an unsent draft for the latest observation. Does not paste or send anything.

Client must first identify new incoming text, merge bursts and skip privacy questions. This server does not claim to enforce semantic privacy classification.

Inputs: text (required), session_id (required), observation_id (required).

start_observationA

Capture baseline for the locally verified contact; never reply to baseline history.

This does not launch a timer. The MCP client must call poll_changes. Requires an image-capable client for subsequent before/after review.

Inputs: duration_seconds, interval_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool maps cleanly to a distinct stage in the observation workflow: status, start, poll, acknowledge, preview, pause, and demo advance. The descriptions carefully separate internal bookkeeping from WeChat-facing actions, so there is little chance of selecting the wrong tool.

    Naming Consistency4/5

    Six of seven tools follow a consistent verb_noun pattern such as get_status, start_observation, poll_changes, acknowledge_observation, preview_reply, and pause_observation. demo_advance is a minor naming outlier, reversing the expected noun-verb order.

    Tool Count5/5

    Seven tools is well-scoped for the intended observation-and-preview workflow. Each tool adds a distinct capability, and demo_advance is clearly labeled as demo-only rather than bloating the surface area.

    Completeness5/5

    The toolset covers the full lifecycle from baseline capture through polling, acknowledgment, reply preview, and pause/restart. The absence of a send action is intentional and consistently documented, so the surface feels complete for its stated no-send, human-in-the-loop purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables automation of WeChat on macOS through the Accessibility API, allowing LLMs to fetch recent messages from contacts and send replies based on conversation history.
      88 PyPI
      301
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI clients read-only access to WeChat chat history by extracting and decrypting the local Mac database, enabling search, summary, and analysis of messages.
      1
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables macOS WeChat desktop clients to read conversations via OCR, retrieve encrypted session memory, and perform controlled message sending through MCP with dry-run and supervised safeguards.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read the local, already-logged-in WeChat account's chat history: fetch recent messages per contact for reply suggestions, bulk-export all conversations into a local SQLite index for full-text and semantic search, and export media or Moments timelines as offline HTML. Everything runs locally and read-only on macOS, exposing 15 MCP tools plus a matching CLI.
      GPL 3.0