Metadata-Version: 2.4
Name: wechat-mcp-macos
Version: 0.1.0
Summary: MCP server for reading and sending WeChat messages on macOS
Project-URL: Homepage, https://github.com/SsssssSynqa/wechat-mcp-macos
Project-URL: Repository, https://github.com/SsssssSynqa/wechat-mcp-macos
Project-URL: Issues, https://github.com/SsssssSynqa/wechat-mcp-macos/issues
Author-email: Synqa <synqa@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,macos,mcp,wechat
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: zstandard>=0.22.0
Description-Content-Type: text/markdown

# wechat-mcp-macos

An MCP (Model Context Protocol) server that lets AI assistants read and send WeChat messages on macOS.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

一个 MCP 服务器，让 AI 助手在 macOS 上读取和发送微信消息。

## How It Works / 工作原理

**Reading messages**: Decrypts the local WeChat SQLite database (SQLCipher 4, AES-256-CBC) and queries it directly. This is fast, accurate, and doesn't require screenshots or OCR.

**Sending messages**: Uses macOS `osascript` (AppleScript) to automate the WeChat desktop client — sets the clipboard, clicks the input box, pastes, and hits Enter.

**读取消息**：解密本地微信 SQLite 数据库（SQLCipher 4, AES-256-CBC）并直接查询。速度快、准确率 100%，不需要截图或 OCR。

**发送消息**：通过 macOS `osascript`（AppleScript）自动化微信桌面客户端——设置剪贴板、点击输入框、粘贴、回车发送。

## Requirements / 环境要求

- macOS (tested on macOS 15 Sequoia)
- WeChat desktop client (微信 Mac 版)
- Python 3.10+
- Xcode command-line tools (`xcode-select --install`)

## Installation / 安装

```bash
# With uv (recommended)
uv tool install wechat-mcp-macos

# Or with pip
pip install wechat-mcp-macos
```

### Connect to Claude Code / 连接 Claude Code

```bash
claude mcp add wechat -- wechat-mcp-macos
```

### Connect to Claude Desktop / 连接 Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wechat": {
      "command": "wechat-mcp-macos"
    }
  }
}
```

## First-Time Setup / 首次配置

The first time you use it, you need to set up WeChat database access:

首次使用需要配置微信数据库访问：

### 1. Re-sign WeChat / 重签名微信

WeChat ships with hardened runtime, which prevents memory scanning for encryption keys. You need to re-sign it:

微信自带 hardened runtime，需要重签名才能提取密钥：

```
# Quit WeChat first! / 先退出微信！
# Then ask your AI to run:
setup("sign")
```

Or manually:
```bash
sudo codesign --force --deep --sign - /Applications/WeChat.app
```

> **Note**: After re-signing, you may need to re-authorize WeChat's screen recording permission in System Settings → Privacy & Security → Screen Recording. Run `tccutil reset ScreenCapture com.tencent.xinWeChat` then restart WeChat.
>
> **注意**：重签名后可能需要重新授权微信的录屏权限。

### 2. Extract encryption keys / 提取加密密钥

Start WeChat and log in, then:

启动微信并登录，然后：

```
setup("extract")
```

This compiles a C memory scanner, scans the WeChat process for SQLCipher keys, and saves them to `~/.wechat-mcp/all_keys.json`.

这会编译一个 C 内存扫描器，从微信进程中提取 SQLCipher 密钥。

### 3. Verify / 验证

```
get_status()
```

If everything says "ready", you're good to go!

如果一切显示"ready"，就可以开始使用了！

## MCP Tools / 可用工具

| Tool | Description |
|------|-------------|
| `get_status()` | Health check: config, keys, WeChat process status |
| `setup(step)` | Guided setup: "detect", "sign", "extract", or "auto" |
| `list_chats(limit)` | Recent conversations with timestamps and previews |
| `read_messages(chat, limit, since_hours)` | Read messages from any chat |
| `search(keywords, chat_names, hours_back)` | Cross-chat keyword search |
| `list_groups()` | List all group chats |
| `send(text, chat)` | Send a message (requires Accessibility permission) |

## Usage Examples / 使用示例

Once connected to your AI client:

```
"Show me my recent WeChat messages"
→ list_chats() + read_messages()

"Search for messages about 'dinner' in the last week"
→ search(keywords="dinner", hours_back=168)

"Send 'I'll be there in 10 minutes' to Mom"
→ send(text="I'll be there in 10 minutes", chat="Mom")
```

## Sending Messages / 发送消息

To send messages, the app running the MCP server needs **Accessibility** permission:

发送消息需要**辅助功能**权限：

System Settings → Privacy & Security → Accessibility → Enable your terminal app / Claude.app

系统设置 → 隐私与安全性 → 辅助功能 → 启用终端 / Claude.app

## Configuration / 配置

Config is stored at `~/.wechat-mcp/config.json`:

```json
{
  "db_dir": "/path/to/wechat/db_storage",
  "keys_file": "~/.wechat-mcp/all_keys.json",
  "decrypted_dir": "~/.wechat-mcp/decrypted",
  "self_name": "Me"
}
```

- `self_name`: Display name for your own messages (they have empty sender in the DB)

If you previously used [wechat-summary-share](https://github.com/ylytdeng/wechat-summary-share), config will be auto-migrated from `~/.wechat-summary/`.

## Known Limitations / 已知限制

- **macOS only** — uses Mach VM APIs for key extraction and osascript for sending
- **Read-only database** — the database is decrypted as a copy, original files are never modified
- **WeChat updates may break key extraction** — re-sign and re-extract keys after updates
- **Cannot read image/video/voice content** — only shows `[图片]` `[视频]` `[语音]` markers
- **Sending requires UI automation** — WeChat window must be accessible

## Credits / 致谢

- **[ylytdeng/wechat-decrypt](https://github.com/nicholaschenai/wechat-decrypt)**: C memory scanner and SQLCipher 4 decryption logic
- **Zhan (盏)**: WeChatDB query interface, message parsing, FTS search, zstd decompression

## License

MIT
