wecom-msg-audit-mcp

企业微信会话内容存档 MCP 服务：拉取、解密并查询聊天记录，让 AI Agent 拥有合规可审计的会话访问能力。

---

特性

• 🔌 MCP 协议：基于 FastMCP 暴露工具，兼容 Cursor、Claude Desktop、Cline 等 MCP 客户端
• 🔐 完整解密链路：封装企业微信官方 libWeWorkFinanceSdk_C.so，自动处理 RSA 私钥解密 + SDK 对称解密
• 📨 多种消息类型：支持文本、图片、视频、语音、文件、链接、位置、名片、表情、视频号、混排等
• 🗂️ 本地检索：解密结果持久化为 JSONL，支持按群、发送者、消息类型、关键词查询与分页
• 👥 群资料查询：自动识别内部群 / 外部客户群，补全群名称、成员列表
• ☁️ 媒体上传：图片自动上传到 Cloudflare R2 并返回预签名链接（其他文件保存到本地）
• 🛡️ Bearer 鉴权：内置 Token 校验，支持 stdio / http 两种传输

架构

┌────────────────────┐
│  MCP 客户端         │
│  (Cursor / Claude) │
└─────────┬──────────┘
          │ MCP (stdio / http + Bearer)
          ▼
┌────────────────────┐
│  mcp_server.py     │  FastMCP 工具定义
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│  wecom_core.py     │  配置 / 业务逻辑
└─────────┬──────────┘
          │ ctypes
          ▼
┌────────────────────┐    ┌──────────────┐
│  libWeWorkFinance  │◄──►│  企业微信 API │
│  SDK_C.so (官方)    │    └──────────────┘
└────────────────────┘

快速开始

1. 前置条件

拉取会话内容需要先在企业微信管理后台（work.weixin.qq.com）开启会话存档功能。开启方式和 API 参数说明见企业微信开发者文档。

• Python 3.11+

• 企业微信会话内容存档权限：登录 管理后台 → 安全与管理 → 管理工具 → 会话内容存档

• 企业微信官方 SDK：libWeWorkFinanceSdk_C.so（需自行从开放平台下载）

• RSA 私钥：在管理后台「会话内容存档」页面上传公钥，私钥用 openssl 在本地生成（不要使用任何在线生成工具，避免私钥外泄）：

  # 生成 2048 位 RSA 私钥（兼容企业微信会话存档）
  openssl genrsa -out private_key.pem 2048
  
  # 提取对应公钥，上传到管理后台
  openssl rsa -in private_key.pem -pubout -out public_key.pem
  

2. 安装

git clone https://github.com/deadmau5v/wecom-msg-audit-mcp.git
cd wecom-msg-audit-mcp

# 推荐使用 uv
uv sync

# 或使用 pip
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

将官方 SDK 文件 libWeWorkFinanceSdk_C.so 放置到项目根目录（或在 .env 中自定义 SDK_LIB_PATH）。

3. 配置

cp .env.example .env
# 编辑 .env，填入企业 ID、Secret、私钥路径等

4. 启动

作为 MCP 服务（推荐）

# stdio 模式（默认）
uv run python mcp_server.py

# http 模式（带 Bearer 鉴权）
MCP_TRANSPORT=http MCP_PORT=8331 uv run python mcp_server.py

然后在 MCP 客户端配置中接入：

{
  "mcpServers": {
    "wecom": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/wecom-msg-audit-mcp"
    }
  }
}

作为 CLI 拉取

uv run python main.py

输出解密后的消息到 stdout，并增量追加到 wecom_messages.jsonl。

配置项

所有配置通过环境变量（或 .env 文件）注入，禁止硬编码到代码中。

变量	必填	说明
CORP_ID	✅	企业 ID（我的企业 → 企业信息）
MSGAUDIT_SECRET	✅	会话内容存档 Secret（不是普通应用 Secret）
EXTERNAL_CONTACT_SECRET	⬜	客户联系可调用应用 Secret（用于外部客户群）
SDK_LIB_PATH	⬜	SDK 动态库路径，默认 ./libWeWorkFinanceSdk_C.so
PRIVATE_KEY_PATH	⬜	RSA 私钥路径，默认 ./private_key.pem
SEQ_FILE	⬜	seq 进度文件，默认 ./wecom_msg_seq.txt
OUTPUT_JSONL	⬜	解密消息输出文件，默认 ./wecom_messages.jsonl
FETCH_LIMIT	⬜	单次拉取条数，1-1000，默认 100
SDK_TIMEOUT	⬜	SDK 请求超时（秒），默认 30
PROXY / PROXY_PASSWORD	⬜	代理与代理密码（按需）
R2_ENDPOINT	⬜	Cloudflare R2 端点，例：https://xxx.r2.cloudflarestorage.com/<bucket>
R2_BUCKET	⬜	R2 存储桶（若已包含在 endpoint 路径中可省略）
R2_CUSTOM_DOMAIN	⬜	自定义访问域名（用于预签名 URL 替换）
R2_TOKEN	⬜	兼容字段（当前未使用，可保留）
R2_S3_ID / R2_S3_KEY	⬜	R2 S3 兼容 AccessKey
MCP_BEARER_TOKEN	⬜	HTTP 模式下的 Bearer 鉴权 Token，留空则自动生成
MCP_TRANSPORT	⬜	stdio（默认）或 http
MCP_HOST / MCP_PORT	⬜	HTTP 模式监听地址，默认 127.0.0.1:8331

完整示例见 .env.example。

MCP 工具一览

工具	用途
wecom_get_config_status	检查服务就绪状态（各能力是否可用）
wecom_pull_messages	从当前 seq 拉取并解密新消息
wecom_get_seq / wecom_set_seq	查看 / 重置拉取进度
wecom_query_messages	按群、发送者、类型、关键词检索本地消息
wecom_extract_roomids	从本地消息中提取所有群聊 roomid
wecom_get_group_info	查询群聊详情（内部 / 外部自动判定）
wecom_list_external_groups	列出外部客户群
wecom_download_media	下载 / 上传消息中的媒体文件

示例：让 Agent 拉取并搜索

User: 帮我拉取最近的聊天记录，搜索包含"发票"的消息

Agent: 调用 wecom_pull_messages → 解密
       调用 wecom_query_messages(keyword="发票", limit=20) → 返回结果

安全提醒

⚠️ 本项目会处理企业敏感数据，部署前请仔细阅读本节。

1. .env 绝不能提交到仓库——本项目已通过 .gitignore 默认忽略；首次 git add 前请确认。
2. private_key.pem 绝不能提交——同理已忽略。若不慎泄露，请立即在企业微信管理后台 重置公钥。
3. 消息数据可能包含个人隐私——wecom_messages.jsonl、群资料导出文件等已加入 .gitignore，请勿外发。
4. Bearer Token 默认会写入 .env——HTTP 模式启动时若未设置 MCP_BEARER_TOKEN，会自动生成并保存到 .env；若希望每次启动都使用临时 Token，请改为外部注入或自行改造启动脚本。
5. 部署时建议：
   • 使用反向代理（HTTPS + IP 白名单）暴露 MCP HTTP 端点
   • 定期轮换 MSGAUDIT_SECRET 和 RSA 密钥对
   • 限制 OUTPUT_JSONL 所在目录的访问权限

项目结构

.
├── mcp_server.py        # FastMCP 入口，工具定义
├── wecom_core.py        # 核心业务：配置、SDK 封装、解密、查询
├── main.py              # CLI 入口：拉取并打印消息
├── group_chat.py        # 群资料识别与导出脚本
├── test_mcp_all.py      # MCP 工具冒烟测试
├── restart.sh           # tmux 一键重启脚本
├── fastmcp.json         # FastMCP 客户端配置
├── pyproject.toml       # 项目元数据
├── requirements.txt     # pip 依赖
├── .env.example         # 配置示例
├── .gitignore
├── LICENSE
└── README.md

开发

# 启动 HTTP 模式做本地调试
MCP_TRANSPORT=http MCP_PORT=8331 uv run python mcp_server.py

# 跑冒烟测试（需要先启动服务）
uv run python test_mcp_all.py

常见问题

Q: 启动报 SDK 动态库不存在？ A: 检查 .env 中 SDK_LIB_PATH 是否指向正确的 .so 文件，且有可执行权限。

Q: 报 RSA 解密 encrypt_random_key 失败？ A: 私钥与后台公钥版本不匹配，需在管理后台重新下载配套私钥。

Q: 报 errcode=60011？ A: 表示企业没有开通「会话内容存档」权限，需管理员在后台申请。

License

MIT