<div align="center">

# WeChat MCP Excel Contact Server

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Install via GitHub](https://img.shields.io/badge/install-GitHub-181717.svg)](https://github.com/zbvxbb622-code/wechat-mcp-friend-automation)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[中文](docs/README_zh.md) | English

</div>

An MCP server that automates WeChat on macOS using Accessibility APIs and screen capture. This package focuses on Excel-driven contact requests, reusable add-friend flows, and friend-request status checks for local outreach workflows.

## Features

- 📨 Fetch recent messages from any chat (contact or group)
- ✍️ Send automated replies based on chat history
- 📷 Publish text-only Moments posts, with optional draft-only mode
- 👥 Add contacts using WeChat ID with configurable privacy
- 📊 Read selected Excel rows into WeChat contact request payloads
- 🔁 Monitor pending friend requests, classify whether they were accepted, and persist local state for later processing
- 🧾 Write operator-friendly CSV state plus JSONL audit events
- 🔍 Smart chat search with exact name matching
- 🤖 5 specialized Claude Code sub-agents for smart WeChat automation

## Quick Start

### Installation

```bash
uv tool install git+https://github.com/zbvxbb622-code/wechat-mcp-friend-automation.git
```

After installation, initialize the local state files and print the exact
first-run commands:

```bash
wechat-mcp-bootstrap
wechat-mcp-doctor
```

`wechat-mcp-bootstrap` safely creates the default `wechat-followup-state/`
directory, `monitor_state.csv`, `monitor_events.jsonl`, the production
`wechat-outreach-state/` directory, and the default `logs/` directory without
overwriting existing files. `wechat-mcp-doctor` reports
`PASS` or `ACTION REQUIRED` for the Python/uv runtime boundary, WeChat
installation and login, macOS Accessibility readiness, writable state, and MCP
registration guidance. The installed console scripts run directly; `uv` is
needed for this install command and for the source-checkout workflow below,
not for the already-installed `wechat-mcp` command.

### Setup with Claude Code

```bash
# If installed as a uv tool
claude mcp add --transport stdio wechat-mcp -- wechat-mcp

# If using uv for development
claude mcp add --transport stdio wechat-mcp -- uv --directory $(pwd) run wechat-mcp
```

<details>
<summary>Setup with Claude Desktop</summary>

```json
// If installed as a uv tool
{
  "mcpServers": {
    "wechat-mcp": {
      "type": "stdio",
      "command": "wechat-mcp"
    }
  }
}

// If using uv for development
{
  "mcpServers": {
    "wechat-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "{path/to/wechat-mcp}",
        "run",
        "wechat-mcp"
      ],
    }
  }
}
```

</details>

<details>
<summary>Setup with Codex</summary>

```bash
# If installed as a uv tool
codex mcp add wechat-mcp -- wechat-mcp

# If using uv for development
codex mcp add wechat-mcp -- uv --directory $(pwd) run wechat-mcp
```

</details>

### macOS Permissions

⚠️ **Important**: Grant Accessibility permissions to your terminal:

1. Open WeChat for Mac and sign in with the QR code or phone login.
2. Open **System Settings → Privacy & Security → Accessibility**
3. Add and enable the terminal/IDE that launches the MCP command (Terminal.app, iTerm2, etc.)
4. Run `wechat-mcp-doctor` and resolve every `ACTION REQUIRED` check before using the server.

The bootstrap command prints these one-time steps and both exact registration
commands:

```bash
# Claude Code
claude mcp add --transport stdio wechat-mcp -- wechat-mcp

# Codex
codex mcp add wechat-mcp -- wechat-mcp
```

## Usage

### Basic Commands

```bash
# Re-run first-run checks at any time
wechat-mcp-doctor

# Run one production outreach scheduling pass
wechat-outreach-run --input-xlsx /path/to/contacts.xlsx --sheet-name 独家达人 --once

# Run with default stdio transport
wechat-mcp --transport stdio

# Run with HTTP transport
wechat-mcp --transport streamable-http

# Run with SSE transport
wechat-mcp --transport sse

# Poll pending friend requests once and write monitor_state.csv / monitor_events.jsonl
wechat-followup-monitor --workbook /path/to/contacts.xlsx --sheet-name 独家达人 --rows 3-6 --once
```

### Available MCP Tools

- **`fetch_messages_by_chat`** - Get recent messages from a chat
- **`reply_to_messages_by_chat`** - Send a reply to a chat
- **`add_contact_by_wechat_id`** - Add a new contact using a WeChat ID and send a friend request
- **`read_wechat_contacts_from_excel`** - Read selected Excel rows into friend-request payloads
- **`add_contacts_from_excel_rows`** - Read selected Excel rows and add contacts
- **`check_contact_status`** - Classify a contact as `added`, `waiting`, `not_added`, `not_found`, or `unknown`
- **`publish_moment_without_media`** - Publish a text-only Moments post (no photos or videos); optionally only prepare a draft without posting via `publish=False`

See [detailed API documentation](docs/detailed-guide.md) for full tool specifications.

The repository also includes local follow-up helpers and runner scripts for stateful workflows, but the default MCP registry intentionally keeps direct accepted-contact send tools hidden.

### Excel Contact Workflow

Defaults match the tested creator resource sheet:

- `nickname_col`: `B`
- `redbook_id_col`: `C`
- `wechat_id_col`: `AZ`
- `start_row`: `3`
- `request_message`: `你好，想和你沟通商务合作`
- `remark_template`: `小红书-{nickname}-{redbook_id}`
- Batch add delay: `delay_seconds=10` by default between contacts
- Cooldown: after every 20 contacts, wait 10 minutes before continuing
- Cooldown check: re-check pending contacts after cooldown, update local state files, and record unresolved contacts for later processing
- Optional shared QR image: pass one `followup_image_path` / `--followup-image` and the same QR image is sent to every accepted contact after the text message

Example MCP arguments for a preview:

```json
{
  "workbook_path": "/path/to/contacts.xlsx",
  "sheet_name": "独家达人",
  "rows": "3,5-8"
}
```

Example MCP arguments for a dry run:

```json
{
  "workbook_path": "/path/to/contacts.xlsx",
  "sheet_name": "独家达人",
  "rows": "3-6",
  "dry_run": true
}
```

When running a real batch, the server spaces out add attempts and cools down after every 20 contacts by default:

```json
{
  "workbook_path": "/path/to/contacts.xlsx",
  "sheet_name": "独家达人",
  "rows": "3-42",
  "delay_seconds": 10,
  "cooldown_after_contacts": 20,
  "cooldown_seconds": 600,
  "followup_image_path": "/path/to/wecom-qr.png"
}
```

### Follow-Up Monitor

This repository includes local follow-up helpers for operator-run workflows. Direct accepted-contact send helpers are not registered as default MCP tools.

`wechat-followup-monitor` keeps the post-request workflow running without leaving a Codex chat open.

Defaults:

- Check interval: 30 minutes
- Max wait: 72 hours
- State files: `wechat-followup-state/monitor_state.csv` and `wechat-followup-state/monitor_events.jsonl`
- Follow-up message: `你好，想和你进一步沟通商务合作，方便时请回复这条消息`
- Send failures are recorded as `send_failed` and are not retried automatically

Run `wechat-mcp-bootstrap --state-dir /path/to/wechat-followup-state` to create
these state files before the first batch or monitor run. Existing CSV/JSONL
files are preserved.

Example:

```bash
wechat-followup-monitor \
  --workbook /path/to/contacts.xlsx \
  --sheet-name 独家达人 \
  --rows 3-6 \
  --followup-image /path/to/wecom-qr.png
```

For a safe test without touching WeChat:

```bash
wechat-followup-monitor \
  --workbook /path/to/contacts.xlsx \
  --rows 3 \
  --once \
  --dry-run \
  --dry-run-status waiting
```

### Production Outreach Runner

`wechat-outreach-run` is the production closed-loop entrypoint. It keeps an
internal queue in `wechat-outreach-state/run_state.json`, exports operator
views as:

- `wechat-outreach-state/输入快照.xlsx`
- `wechat-outreach-state/待处理表.xlsx`
- `wechat-outreach-state/成功表.xlsx`
- `wechat-outreach-state/失败表.xlsx`

Default behavior:

- Work window: `10:00-24:00` local time
- One WeChat action at a time
- Global deduplication by `wechat_id`
- Fixed follow-up delay: `5-15` minutes after acceptance
- Single-instance lock: `wechat-outreach-state/.wechat-outreach.lock`
- Circuit-breaker evidence: `wechat-outreach-state/evidence/`

Resume after a pause:

- `wechat-outreach-run --state-dir /path/to/wechat-outreach-state --resume`
- When a circuit breaker pauses the run, resume only continues unfinished
  people from `待处理表.xlsx`.
- `成功表.xlsx` and `失败表.xlsx` are never retried automatically.

Example:

```bash
wechat-outreach-run \
  --input-xlsx /path/to/contacts.xlsx \
  --sheet-name 独家达人 \
  --rows 3-40 \
  --followup-image /path/to/wecom-qr.png
```

## Claude Code Sub-Agents

This project includes 5 intelligent sub-agents designed specifically for WeChat automation. They enable natural language control of WeChat through Claude Code.

### Available Sub-Agents

1. **Chat-summarizer** - Summarize chat history and extract key information
2. **Auto-replier** - Auto-generate and send appropriate replies
3. **Message-searcher** - Search chat history for specific content
4. **Multi-chat-checker** - Monitor multiple chats and prioritize messages
5. **Chat-insights** - Analyze relationship dynamics and communication patterns

📖 [View complete sub-agents guide](.claude/agents/README.md)

## Development

### Local Setup with uv

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/zbvxbb622-code/wechat-mcp-friend-automation.git
cd wechat-mcp-friend-automation
uv sync

# Run locally
uv run wechat-mcp --transport stdio

# Run the install checks from a source checkout
uv run wechat-mcp-bootstrap
uv run wechat-mcp-doctor
```

## Documentation

- 📘 [Detailed Guide](docs/detailed-guide.md) - Complete API documentation and architecture
- 🤖 [Sub-Agents Guide](.claude/agents/README.md) - How to use Claude Code sub-agents

## Requirements

- macOS (uses Accessibility API)
- WeChat for Mac installed and running
- Python 3.12+
- Accessibility permissions for terminal

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details