关键词

WhatsApp聊天记录消息检索联系人LLM上下文

项目简介

本项目 'just-my-kids' 的核心组件之一是 'whatsapp-mcp-server'，它基于 Model Context Protocol (MCP) 构建，旨在将用户的 WhatsApp 聊天数据（包括消息记录、联系人信息等）以结构化的方式暴露给支持 MCP 协议的 LLM 客户端，例如 Claude 或 Cursor。通过此 MCP 服务器，LLM 客户端可以便捷地访问和利用 WhatsApp 数据，实现更智能的对话和信息检索功能。

请注意： 'just-my-kids' 项目的完整功能还包括基于人脸识别的照片过滤，但本分析报告仅关注其 MCP 服务器实现 部分。

主要功能点

  • 消息检索: 允许 LLM 客户端查询 WhatsApp 消息，支持按日期范围、发送者、聊天对象、关键词等条件进行过滤。
  • 聊天记录访问: 提供对 WhatsApp 聊天会话的访问，包括群组和个人聊天。
  • 联系人查询: 支持 LLM 客户端搜索 WhatsApp 联系人信息。
  • 消息上下文: 能够获取特定消息的上下文信息，包括其前后一段时间的消息记录。
  • 发送消息: 允许 LLM 客户端通过服务器发送 WhatsApp 消息。
  • 资源与工具: 将 WhatsApp 聊天数据作为 资源 (Resources) 提供，并将消息查询、发送等功能作为 工具 (Tools) 注册到 MCP 服务器。
  • 标准协议: 使用 JSON-RPC over Stdio 协议与 MCP 客户端通信，符合 MCP 标准。

安装步骤

  1. 克隆仓库

    git clone https://github.com/Yakirbe/just-my-kids.git
cd just-my-kids

  2. 安装 Python 依赖

    pip install -r requirements.txt

  3. 安装 Go 依赖

    cd whatsapp-bridge
go mod download

  4. 安装 'fastmcp' 库 (如果尚未安装)

    pip install fastmcp

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数，以便建立连接。以下是针对 'whatsapp-mcp-server' 的配置信息示例 (JSON 格式)：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/python",
      "args": [
        "--directory",
        "/full/path/to/just-my-kids/whatsapp-mcp-server",
        "run",
        "main.py"
      ]
    }
  }
}

配置参数说明：

  • '"whatsapp"': 服务器名称，可以自定义。
  • '"command"': Python 解释器的完整路径。请务必替换为您的 Python 解释器实际路径 (例如：'/usr/bin/python3' 或 'C:\Python39\python.exe')。 您可以使用 'which python' (Linux/macOS) 或 'where python' (Windows) 命令查找 Python 路径。
  • '"args"': 传递给 Python 脚本的参数列表。
    • '"--directory"': 指定 'whatsapp-mcp-server' 目录的完整路径。 请务必替换为 'just-my-kids' 仓库中 'whatsapp-mcp-server' 目录的实际路径 (例如：'/Users/yourname/just-my-kids/whatsapp-mcp-server' 或 'C:\Users\YourName\just-my-kids\whatsapp-mcp-server')。
    • '"run"': 表示运行 MCP 服务器。
    • '"main.py"': 指定 MCP 服务器的入口脚本。

MCP 客户端配置示例 (以 Claude Desktop 或 Cursor 为例):

将上述 JSON 配置添加到 Claude Desktop 的 'claude_desktop_config.json' 文件 ('~/Library/Application Support/Claude/claude_desktop_config.json' on macOS) 或 Cursor 的 'mcp.json' 文件 ('~/.cursor/mcp.json') 中。

基本使用方法

  1. 启动 WhatsApp Bridge: 首先，您需要启动 'whatsapp-bridge' 组件，它负责连接 WhatsApp 并将消息存储到数据库。

    cd whatsapp-bridge
go run main.go

    首次运行时，会生成二维码，请使用您的 WhatsApp 扫描二维码登录。

  2. 启动 MCP 服务器: 在新的终端窗口中，导航到 'whatsapp-mcp-server' 目录并启动 MCP 服务器。

    cd whatsapp-mcp-server
python main.py run stdio

    或者，如果您已在 MCP 客户端配置中指定了正确的启动命令和参数，则无需手动运行此命令，MCP 客户端会自动启动服务器。

  3. 在 MCP 客户端中使用: 启动支持 MCP 协议的 LLM 客户端 (例如 Claude Desktop 或 Cursor)，并按照其文档指示，选择已配置的 "whatsapp" MCP 服务器。您现在应该可以在 LLM 客户端中使用注册的工具来访问和操作 WhatsApp 数据。

    例如，在 Claude 中，您可以使用 '@whatsapp' 前缀来调用 WhatsApp MCP 服务器提供的工具，例如：

    @whatsapp/list_messages query="会议" limit=5

    这将调用 'list_messages' 工具，搜索包含关键词 "会议" 的最近 5 条 WhatsApp 消息。

注意:

  • 确保 'whatsapp-bridge' 组件先于 MCP 服务器启动并成功连接到 WhatsApp。
  • MCP 客户端的具体使用方法请参考其官方文档。

信息

分类

通信与社交

访问项目