weixin-mcp-server

微信 MCP Server，基于 pyweixin，兼容微信 4.1+（最新 4.1.12）。通过标准 MCP 协议接入，让 AI 助手能驱动桌面微信发消息、发文件、查聊天记录等。

特性

• ✅ 兼容微信 4.1.12（最新官方版）
• ✅ 基于 pyweixin（非 pywechat），pyweixin 已内置（vendored）于仓库，开箱即用，无需额外安装
• ✅ 9 个 MCP 工具：发消息、发文件、查聊天记录、搜索联系人等
• ✅ 通过标准 MCP 协议接入（Hermes / WorkBuddy / Claude Desktop 等）
• ✅ 不再依赖 cwd：src/server.py 会自动将仓库根加入 sys.path，并推荐以「绝对路径启动 server.py」的方式接入，即使 MCP 客户端未传递工作目录也能正确运行

快速开始

1. 克隆仓库

git clone https://github.com/linnnnnnnnnnnnnnnnnnnnn/weixin-mcp-server.git
cd weixin-mcp-server

2. 安装依赖

# 推荐：用虚拟环境（避免污染系统 Python）
python -m venv .venv
.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 或直接装到当前 Python
pip install -r requirements.txt

Windows 用户也可直接双击 install.bat（已配置清华镜像）。 无需 pip install pyweixin —— 该包未发布到 PyPI，本项目已将其直接内置。

3. 配置 MCP 客户端

推荐用「绝对路径启动 server.py」（如下方示例），这是最稳的方式：不依赖客户端是否传递 cwd，也不需要额外的 PYTHONPATH。 如果你的客户端一定会正确传递 cwd，也可改用 args: ["-m", "src.server"] + cwd 的形式（两者均可）。

Hermes（config.yaml 或 MCP 管理界面）：

mcp_servers:
  weixin-server:
    command: "C:\\path\\to\\weixin-mcp-server\\.venv\\Scripts\\python.exe"
    args: ["C:\\path\\to\\weixin-mcp-server\\src\\server.py"]
    cwd: "C:\\path\\to\\weixin-mcp-server"   # 可省略

WorkBuddy（mcp.json）：

{
  "mcpServers": {
    "weixin-server": {
      "command": "C:\\path\\to\\weixin-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\weixin-mcp-server\\src\\server.py"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "weixin-server": {
      "command": "C:\\path\\to\\weixin-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\weixin-mcp-server\\src\\server.py"]
    }
  }
}

4. 重启客户端

重启 Hermes / WorkBuddy / Claude，MCP 服务器会自动启动。确保微信 PC 版已登录且运行中（pyweixin 通过 UI 自动化驱动微信客户端）。

MCP 工具

工具	功能
wechat_send_message	向好友发送单条消息
wechat_send_multiple_messages	向好友发送多条消息
wechat_send_to_multiple_friends	向多人发送同一条消息
wechat_send_file	向好友发送文件（PDF、图片等）
wechat_search_contacts	搜索微信联系人
wechat_get_chat_history	获取聊天记录
wechat_open_dialog	打开与好友的聊天窗口
wechat_get_status	获取微信运行状态
wechat_run_command	执行系统命令

要求

• Python 3.10+
• 微信 PC 版 4.1+（已登录、运行中）
• Windows（pyweixin 依赖 pywinauto / pywin32 等 Windows 专用库）

第三方组件与许可

本项目将 pyweixin（来自 Hello-Mr-Crab/pywechat，位于仓库根 pyweixin/ 目录）以 vendored 形式内置，以规避其未发布到 PyPI 导致无法 pip install 的问题。其许可遵循上游仓库，使用前请自行查阅上游 LICENSE。

License

MIT