wxauto MCP Server

微信自动化 MCP (Model Context Protocol) 服务器，为 AI 开发工具提供微信自动化能力。

License

功能特性

MCP 协议支持: 完整支持 Model Context Protocol
消息操作: 发送文本、图片、文件、链接卡片消息
联系人管理: 获取好友列表、切换聊天、获取聊天信息
会话管理: 获取会话列表、筛选未读消息
文件传输: 发送单个或批量文件
好友管理: 获取新好友请求、接受好友、添加新好友
多种传输: 支持 stdio、HTTP/SSE 传输方式
AI 工具集成: 支持 Claude Code、Cursor 等开发工具
一键安装: 自动配置到 AI 应用，无需手动编辑配置文件
全局单例: 自动检测并复用已运行的服务器实例，避免资源浪费和冲突

系统要求

Windows 11/10
Python 3.11+
微信已登录
wxautox4 激活

PyPI 自动发布

本项目已配置 PyPI Publishing，推送版本标签即可自动发布：

# 发布新版本
git tag v1.0.1
git push origin v1.0.1

GitHub Actions 会自动构建并创建 Release，PyPI 会自动发布新版本。

快速安装

pip install wxauto-mcp

使用

一键自动安装（推荐）

wxauto-mcp --install

这将自动配置 MCP Server 到 Claude Desktop 和 Claude Code，无需手动编辑配置文件。

生成配置文件

# 生成配置文件到默认目录 (./mcp-configs)
wxauto-mcp --config

# 生成配置文件到指定目录
wxauto-mcp --config /path/to/configs

手动配置

如果需要手动配置，运行：

wxauto-mcp --config mcp-configs

然后将生成的配置文件内容添加到 AI 应用中：

Claude Desktop 配置文件位置：

Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code 配置文件位置：

%USERPROFILE%\.claude.json

Cursor：在 Settings 的 MCP 配置中添加

启动服务器

# stdio 模式 (默认，用于 MCP 客户端)
wxauto-mcp

# HTTP/SSE 模式
wxauto-mcp-http --port 8000

# 指定主机和端口
wxauto-mcp-http --host 0.0.0.0 --port 9000

可用工具（27个）

系统工具（6个）

wechat_initialize - 初始化微信连接
wechat_status - 获取微信运行状态
wechat_activate - 激活 wxautox4
wechat_check_activation - 检查激活状态
wechat_list_tools - 列出所有可用工具
get_my_info - 获取我的微信账号信息

消息工具（6个）

send_message - 发送文本消息
send_url_card - 发送链接卡片
get_messages - 获取当前聊天消息
get_history - 获取历史消息
get_next_new_message - 获取下一个聊天窗口的新消息
send_bulk_messages - 批量发送消息

联系人工具（3个）

get_friends - 获取好友列表
get_chat_info - 获取当前聊天信息
switch_chat - 切换聊天窗口

会话工具（4个）

get_sessions - 获取会话列表
get_recent_groups - 获取最近群聊
filter_sessions - 筛选会话列表
get_unread_sessions - 获取有未读消息的会话

文件工具（4个）

send_files - 发送文件
send_image - 发送图片
send_directory_files - 发送整个目录的文件
check_file_exists - 检查文件是否存在

好友请求工具（3个）

get_new_friends - 获取新的好友请求列表
accept_new_friend - 接受新的好友请求
add_friend - 添加新好友

界面工具（1个）

switch_to_contact - 切换到联系人页面

项目结构

wxauto-mcp/
├── src/wxauto_mcp/          # MCP 服务器实现
│   └── wxauto_mcp/
│       ├── __init__.py       # 模块入口
│       ├── rpc.py            # MCP RPC 基础设施
│       ├── api_*.py          # API 实现
│       └── utils.py          # 工具函数
├── core/                     # 核心功能
│   ├── wechat_wrapper.py    # wxautox4 封装
│   ├── listener.py          # 消息监听
│   ├── models.py            # 数据模型
│   └── config.py            # 配置管理
├── tests/                    # 测试文件
├── README.md                # 本文档
├── LICENSE                  # MIT 许可证
└── pyproject.toml           # 项目配置

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest tests/

架构设计

本项目基于 ida-pro-mcp 的架构设计：

模块化 API: 按功能划分独立的 API 模块
装饰器注册: 使用 @tool 和 @resource 装饰器自动注册
输出限制: 自动限制工具输出长度 (50000 字符)
多传输支持: 支持 stdio、HTTP/SSE 传输方式
类型安全: 使用 Pydantic 进行数据验证

依赖项

mcp>=1.0.0 - Model Context Protocol SDK
wxautox4>=0.2.0 - 微信自动化库
fastapi>=0.115.0 - HTTP 服务器
uvicorn[standard]>=0.32.0 - ASGI 服务器
sse-starlette>=2.1.0 - SSE 支持
pydantic>=2.0.0 - 数据验证

HTTP/SSE 模式

MCP Server 支持 HTTP/SSE 传输模式，适用于需要通过网络访问的场景。

全局单例机制

重要: wxauto-mcp 实现了全局单例机制，确保同一台电脑上只有一个服务器实例运行。

工作原理

自动检测: 当启动 HTTP/SSE 模式时，会自动检查是否已有实例运行
智能复用: 如果检测到运行中的实例，新启动会自动退出并提示复用现有实例
避免冲突: 防止多个实例同时操作微信导致冲突

检查服务器状态

# 检查默认端口 (8181) 的服务器状态
wxauto-mcp --status

# 检查指定端口的服务器状态
wxauto-mcp --status --port 9000

# 使用管理工具检查状态
wxauto-mcpctl status

多个 AI 应用共享服务器

由于单例机制，多个 AI 应用（Claude Desktop、Claude Code、Cursor等）可以安全地共享同一个 wxauto-mcp 服务器：

启动第一个 AI 应用 - 自动启动 wxauto-mcp 服务器
启动其他 AI 应用 - 自动检测并复用已存在的服务器
避免资源浪费 - 只运行一个服务器实例
避免操作冲突 - 只有一个进程操作微信 UI

配置建议: 所有 AI 应用配置中使用相同的 URL（默认 http://localhost:8181/sse）

可用端点

当使用 wxauto-mcp-http 启动服务后，以下端点可用：

GET / - 服务器信息
GET /health - 健康检查
GET /sse - SSE 端点（MCP 协议通信）
POST /messages/?session_id=<id> - 消息端点（MCP 协议通信）

使用示例

# 启动 HTTP 服务器（默认端口 8000）
wxauto-mcp-http

# 指定端口
wxauto-mcp-http --port 9000

# 指定监听地址
wxauto-mcp-http --host 0.0.0.0 --port 8000

MCP 客户端配置

对于 HTTP/SSE 模式，需要在 MCP 客户端配置中使用 url 字段：

{
  "mcpServers": {
    "wxauto": {
      "url": "http://localhost:8000/sse"
    }
  }
}

常见问题

1. 激活

wxautox4 需要激活使用。请访问 https://wxauto.org 获取激活密钥，然后：

# 设置环境变量
set WECHAT_LICENSE_KEY=your-license-key

# 或调用激活工具
wxauto-mcp-http
# 然后调用 wechat_activate 工具

2. 权限问题

确保 Python 有访问微信进程的权限，建议以管理员身份运行。

3. 微信窗口

某些操作需要微信窗口在前台可见，请确保微信窗口未被最小化。

4. 配置文件位置

不同 AI 工具的配置文件位置：

Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code:

Windows: %USERPROFILE%\.claude.json

Cursor:

在 Settings → MCP 中添加配置

联系方式

GitHub Issues: [email protected]

快速开始

基础使用

from core import get_wechat

# 获取 WeChat 实例
wx = get_wechat()

# 检查状态
status = wx.get_status()
if status.is_online:
    print(f"微信在线: {status.account_name}")

# 发送消息
wx.chat_with("张三")
wx.send_message("你好!")

发送文件

# 发送单个文件
wx.send_files("C:/path/to/file.pdf", who="张三")

# 发送多个文件
files = ["file1.pdf", "file2.jpg"]
wx.send_files(files, who="张三")

获取会话列表

sessions = wx.get_sessions()
for session in sessions:
    print(f"{session.name} ({session.time})")

错误处理

from core import get_wechat
from core.exceptions import OfflineError, ChatNotFoundError

wx = get_wechat()

try:
    result = wx.chat_with("张三")
    if not result.success:
        print(f"切换失败: {result.message}")
except OfflineError:
    print("微信未运行")
except ChatNotFoundError as e:
    print(f"找不到聊天: {e}")

配置选项

环境变量

变量名	说明	默认值
`WECHAT_LICENSE_KEY`	激活密钥	-
`WECHAT_RESIZE`	自动调整窗口	True
`WECHAT_DEBUG`	调试模式	False
`WECHAT_LOG_LEVEL`	日志级别	INFO