WeChat Desktop MCP

A production-oriented MCP server that exposes task-level WeChat Desktop automation to AI clients. The MCP layer runs on Bun and TypeScript with the stable Model Context Protocol TypeScript SDK v2. A small native Swift bridge owns all macOS Accessibility and input-event work.

This project automates the visible WeChat for macOS application. It does not use, intercept, or reverse-engineer the WeChat network protocol.

Capabilities

The four tool names from the original Python project are preserved for client compatibility. wechat_status is new and provides a safe readiness probe.

Related MCP server: wx4py-mcp

Why this design

• One dependency-injected MCP server factory is shared by stdio, HTTP, and tests.

• Full Zod v4 input/output schemas produce model documentation, runtime validation, and validated structured results.

• All GUI operations pass through one cancellable FIFO mutex. Concurrent MCP calls cannot race the single WeChat UI state machine.

• Recoverable desktop failures become actionable MCP tool errors with stable codes.

• Exact contact/group matching fails closed and returns candidates instead of clicking a similar result.

• The native bridge is a compiled process with a minimal JSON protocol. MCP handlers do not contain shell, Accessibility, or mouse logic.

• Operational logs are structured JSON on stderr. stdout remains exclusively available to the stdio transport.

• A deterministic fake driver supports complete development and MCP contract testing without a WeChat account.

The primary-source design research is in docs/research/mcp-typescript-sdk-v2-best-practices.md.

Requirements

• macOS 14 or newer on Apple Silicon or Intel

• Bun 1.2.20 or newer

• Xcode Command Line Tools (xcode-select --install)

• WeChat for macOS for native operation

• Accessibility permission for the terminal or MCP host application

Screen Recording permission is reported by the status tool but is not currently required; sender classification uses Accessibility geometry rather than screenshots.

Setup

bun install
bun run build:native
bun run check

The native bridge is built at .build/wechat-bridge. No WeChat login is required to build, type-check, or run the automated test suite.

Before live use:

1. Start WeChat and sign in.

2. Open System Settings → Privacy & Security → Accessibility.

3. Grant access to the application that starts this MCP server (for example Terminal, Codex, or the relevant desktop host).

4. Restart that host and call wechat_status.

Run over stdio

stdio is the default and recommended transport for a local desktop MCP:

bun run start

Example MCP host configuration:

{
  "mcpServers": {
    "wechat-desktop": {
      "command": "bun",
      "args": ["/Users/YOU/Code/wechat-desktop-mcp/src/index.ts"],
      "env": {
        "WECHAT_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

All runtime diagnostics go to stderr. Do not redirect application logs to stdout when using stdio.

Run as HTTP ingress

The Bun Web Standard transport serves modern Streamable HTTP and compatible older clients through the SDK v2 handler:

bun run start -- --transport http
# http://127.0.0.1:3210/mcp

It binds to loopback by default and validates Host and Origin headers. Binding to another interface is rejected unless WECHAT_MCP_AUTH_TOKEN contains a token of at least 16 characters:

WECHAT_MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \
  bun run start -- --transport http --host 0.0.0.0

For use outside one trusted machine, place the endpoint behind TLS and an authenticated reverse proxy. The bearer token is a deployment guard, not a complete multi-user authorization system. Because this server controls a personal desktop session, do not expose it directly to the public internet.

Configuration is documented in .env.example. CLI flags override their equivalent environment values.

Development without WeChat

Use the deterministic driver only for development and protocol tests:

bun run start -- --driver fake

The fake exposes one chat named Test Chat. It never accesses the native WeChat app.

Verification

bun run check       # type-check, lint/format verification, all tests
bun run build       # compile Swift bridge and bundle the Bun entry point

The tests cover pure application behavior, exact-match failures, FIFO serialization, cancellation, every tool through a real SDK client, schema rejection, and a spawned stdio process.

Optional interactive inspection:

bunx @modelcontextprotocol/inspector bun ./src/index.ts --driver fake

Operational constraints

• The native tools require an interactive, unlocked macOS user session.

• WeChat UI changes can invalidate Accessibility identifiers. Failures return a stage and stable error category rather than attempting an unsafe fallback click.

• English and common Simplified Chinese labels are supported in the current selector profile.

• Reading is limited to Accessibility-exposed text. Rich media, reactions, quoted-message structure, and sender identity inside group chats are not fully represented.

• Sender is classified as ME, OTHER, or UNKNOWN from message geometry. Clients must handle UNKNOWN.

• Mutations are not automatically retried. A timeout after a click or Return key can leave the remote result indeterminate.

• Logs intentionally omit contact names and message bodies.

See docs/architecture.md for module boundaries and docs/migration-from-python.md for the migration inventory.

License and attribution

MIT. This implementation preserves the behavior and acknowledges the original MIT-licensed BiboyQG/WeChat-MCP project while replacing its Python/PyObjC architecture.