WeChat MCP Monitor 🔔

一个基于 Model Context Protocol (MCP) 的微信群聊消息监控工具，专为 macOS 设计

✨ 功能特性

🎯 精准监控 - 监控指定的微信群聊，避免信息过载
🔍 智能过滤 - 支持关键词和特定发送者双重过滤
🔔 原生通知 - 使用 macOS 系统通知，无需额外应用
🚀 无需登录 - 基于 macOS 微信客户端，无需扫码
🔌 MCP 集成 - 完美集成 Claude Desktop 和其他 MCP 客户端
⚙️ 灵活配置 - 可自定义检查间隔和通知内容

📋 目录

快速开始
安装
配置
使用方法
MCP 工具
权限设置
故障排除
工作原理
注意事项
技术栈
贡献
许可证

🚀 快速开始

# 1. 克隆仓库
git clone https://github.com/Cybing521/wechat-mcp.git
cd wechat-mcp

# 2. 安装依赖
npm install

# 3. 创建配置文件
cp config.example.json config.json

# 4. 编辑配置文件（填入你的群聊名称、关键词等）
nano config.json

# 5. 构建项目
npm run build

# 6. 配置 Claude Desktop（见下方详细说明）

📦 安装

前置要求

macOS 10.15 或更高版本
Node.js 20.0 或更高版本
微信 macOS 客户端 已安装并登录
辅助功能权限 已授予

安装步骤

# 安装依赖
npm install

# 构建项目
npm run build

⚙️ 配置

1. 创建配置文件

cp config.example.json config.json

2. 编辑配置文件

打开 config.json 并根据你的需求修改：

{
  "monitoredGroups": [
    "工作群",
    "项目讨论组"
  ],
  "keywords": [
    "@所有人",
    "紧急",
    "重要"
  ],
  "monitoredSenders": [
    "老板",
    "项目经理"
  ],
  "notificationTitle": "微信群消息提醒",
  "checkInterval": 5000
}

配置项说明

配置项	类型	说明	默认值
`monitoredGroups`	`string[]`	要监控的群聊名称列表	`[]`
`keywords`	`string[]`	触发通知的关键词列表	`[]`
`monitoredSenders`	`string[]`	触发通知的发送者昵称列表	`[]`
`notificationTitle`	`string`	通知标题	`"微信群消息提醒"`
`checkInterval`	`number`	检查间隔（毫秒）	`5000`

过滤规则

消息会在以下情况触发通知：

✅ 消息来自 monitoredGroups 中的群聊且
✅ 消息包含 keywords 中的任一关键词或发送者在 monitoredSenders 列表中

🎯 使用方法

方式一：作为 MCP 服务器（推荐）

1. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

macOS 路径：

~/Library/Application Support/Claude/claude_desktop_config.json

添加配置：

{
  "mcpServers": {
    "wechat-monitor": {
      "command": "node",
      "args": ["/完整路径/wechat-mcp/dist/index.js"]
    }
  }
}

💡 提示： 将 /完整路径/ 替换为你的实际项目路径

2. 重启 Claude Desktop

配置完成后，重启 Claude Desktop 以加载 MCP 服务器。

3. 使用工具

在 Claude Desktop 中，你可以直接使用以下命令：

请帮我启动微信消息监控

或者直接调用工具：

start_monitoring
stop_monitoring
get_status

方式二：独立运行（测试用）

npm start

⚠️ 注意： 独立运行模式下，MCP 工具无法使用，仅用于测试服务器是否正常启动。

🛠️ MCP 工具

`start_monitoring`

启动微信群聊消息监控。

使用示例：

启动微信监控

返回信息：

监控启动成功提示
检查间隔时间
权限提醒

前置条件：

✅ 微信客户端已打开并登录
✅ 已授予辅助功能权限
✅ 配置文件存在且格式正确

`stop_monitoring`

停止消息监控。

使用示例：

停止微信监控

返回信息：

监控停止确认

`get_status`

查看当前监控状态和配置信息。

使用示例：

查看微信监控状态

返回信息：

{
  "isRunning": true,
  "wechatRunning": true,
  "monitoredGroups": ["工作群", "项目讨论组"],
  "keywords": ["@所有人", "紧急"],
  "monitoredSenders": ["老板"],
  "checkInterval": 5000
}

🔐 权限设置

授予辅助功能权限

此工具需要辅助功能权限才能读取微信窗口内容。

设置步骤：

打开 系统偏好设置
进入 安全性与隐私 > 隐私 > 辅助功能
点击左下角 🔒 解锁（需要管理员密码）
添加以下应用：
- ✅ 终端 (Terminal.app) - 如果通过终端运行
- ✅ Claude Desktop - 如果作为 MCP 服务器运行
确保应用旁边的复选框已勾选

验证权限

运行以下命令测试权限是否生效：

osascript -e 'tell application "System Events" to (name of processes) contains "WeChat"'

如果返回 true 或 false（而不是错误），说明权限已正确设置。

🔧 故障排除

问题 1: "WeChat is not running"

原因： 微信客户端未打开

解决方案：

# 打开微信
open -a WeChat

问题 2: 没有收到通知

可能原因：

未授予辅助功能权限
配置文件中的群聊名称不匹配
关键词或发送者设置不正确

解决方案：

检查权限设置（见上方）
使用 get_status 工具查看当前配置
确认群聊名称与微信中显示的完全一致（包括空格）
检查终端输出的错误信息

问题 3: "Permission denied" 或权限错误

原因： 未授予辅助功能权限

解决方案：

按照权限设置部分的步骤操作
重启终端或 Claude Desktop
重新运行程序

问题 4: 构建失败

原因： 依赖安装不完整或 TypeScript 版本问题

解决方案：

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install
npm run build

问题 5: 监控延迟

原因： checkInterval 设置过大

解决方案： 在 config.json 中调整 checkInterval：

{
  "checkInterval": 3000  // 改为 3 秒检查一次
}

⚠️ 注意： 间隔过小可能增加系统负担

🔍 工作原理

┌─────────────────┐
│  MCP Client     │
│ (Claude Desktop)│
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────┐
│  MCP Server     │
│  (本工具)        │
└────────┬────────┘
         │
         │ AppleScript
         │
┌────────▼────────┐
│  macOS          │
│  Accessibility  │
│  API            │
└────────┬────────┘
         │
         │ 读取窗口内容
         │
┌────────▼────────┐
│  WeChat macOS   │
│  Client         │
└─────────────────┘

工作流程

定期轮询 - 根据 checkInterval 设置，定期检查微信窗口
内容提取 - 使用 AppleScript 和 Accessibility API 读取窗口文本
消息解析 - 解析文本内容，识别群聊和消息
规则匹配 - 根据配置的关键词和发送者进行过滤
通知推送 - 匹配成功时通过 macOS 原生通知提醒

⚠️ 注意事项

使用限制

✅ 仅支持 macOS - 依赖 macOS 特有的 AppleScript 和 Accessibility API
✅ 需要微信客户端 - 必须使用 macOS 版微信客户端
✅ 依赖界面结构 - 微信客户端更新可能影响功能
✅ 轮询机制 - 基于定期检查，存在延迟（取决于 checkInterval）

隐私和安全

🔒 本地运行 - 所有数据处理均在本地进行
🔒 无数据上传 - 不会将消息内容发送到任何服务器
🔒 配置文件 - 敏感配置存储在本地 config.json
🔒 开源透明 - 代码完全开源，可自行审查

性能考虑

⚡ CPU 使用 - 轮询会占用少量 CPU 资源
⚡ 内存占用 - 约 50-100MB 内存
⚡ 检查间隔 - 建议设置在 3-10 秒之间

🛠️ 技术栈

TypeScript - 类型安全的 JavaScript
Node.js - JavaScript 运行时
MCP SDK - Model Context Protocol SDK
AppleScript - macOS 自动化脚本
node-notifier - 跨平台通知库

📝 开发

项目结构

wechat-mcp/
├── src/
│   └── index.ts          # 主程序入口
├── dist/                 # 编译输出目录
├── config.json           # 配置文件（需自行创建）
├── config.example.json   # 配置文件模板
├── package.json          # 项目依赖
├── tsconfig.json         # TypeScript 配置
├── README.md             # 项目文档
└── .gitignore            # Git 忽略文件

开发命令

# 开发模式（编译并运行）
npm run dev

# 仅编译
npm run build

# 运行（需先编译）
npm start

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

贡献步骤

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

报告问题

如果遇到问题，请在 Issues 中报告，并提供：

macOS 版本
微信版本
错误信息
复现步骤

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

Model Context Protocol - 提供 MCP SDK
Anthropic - Claude Desktop 和 MCP 生态
所有贡献者和使用者

📮 联系方式

Issues: GitHub Issues
Discussions: GitHub Discussions

如果这个项目对你有帮助，请给个 ⭐️ Star！

Made with ❤️ by Cybing521

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
setup-guide.sh		setup-guide.sh
tsconfig.json		tsconfig.json

License

Cybing521/wechat-mcp

Folders and files

Latest commit

History

Repository files navigation

WeChat MCP Monitor 🔔

✨ 功能特性

📋 目录

🚀 快速开始

📦 安装

前置要求

安装步骤

⚙️ 配置

1. 创建配置文件

2. 编辑配置文件

配置项说明

过滤规则

🎯 使用方法

方式一：作为 MCP 服务器（推荐）

1. 配置 Claude Desktop

2. 重启 Claude Desktop

3. 使用工具

方式二：独立运行（测试用）

🛠️ MCP 工具

start_monitoring

stop_monitoring

get_status

🔐 权限设置

授予辅助功能权限

设置步骤：

验证权限

🔧 故障排除

问题 1: "WeChat is not running"

问题 2: 没有收到通知

问题 3: "Permission denied" 或权限错误

问题 4: 构建失败

问题 5: 监控延迟

🔍 工作原理

工作流程

⚠️ 注意事项

使用限制

隐私和安全

性能考虑

🛠️ 技术栈

📝 开发

项目结构

开发命令

🤝 贡献

贡献步骤

报告问题

📄 许可证

🙏 致谢

📮 联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`start_monitoring`

`stop_monitoring`

`get_status`

Packages