使用说明

WhatsApp MCP

MCP服务器，用于使用向量嵌入和Milvus对WhatsApp对话进行语义搜索。

特性

语义搜索：按含义查找消息，而不仅仅是关键字
多语言支持：适用于使用多语言嵌入的任何语言
日期和发件人筛选：按时间范围或参与者缩小搜索范围
Claude桌面集成：使用Claude Desktop作为MCP服务器
CLI工具：用于数据摄取和搜索的命令行界面

建筑

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│  WhatsApp MCP    │────▶│     Milvus      │
│  (MCP Client)   │     │  (FastMCP Server)│     │  (Vector DB)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │ Sentence         │
                        │ Transformers     │
                        │ (Embeddings)     │
                        └──────────────────┘

先决条件

Python 3.11+
Docker和Docker Compose
紫外线（推荐）或pip

安装

1.克隆存储库

git clone https://github.com/laurentvaldes/whatsapp-mcp.git
cd whatsapp-mcp

2.创建虚拟环境

# Using uv (recommended)
uv venv
source .venv/bin/activate

# Or using Python
python -m venv .venv
source .venv/bin/activate

3.安装依赖项

# Using uv
uv pip install -e ".[server]"

# Or using pip
pip install -e ".[server]"

4.启动基础设施

docker compose up -d

这将开始：

米尔维斯 （端口19530）：用于存储嵌入的矢量数据库
etcd：Milvus的元数据存储
MinIO （端口9000-9001）：Milvus的对象存储

验证容器是否正在运行：

docker compose ps

用法

导出WhatsApp对话

在手机上打开WhatsApp
进入对话→ 设置→ 导出聊天
选择“无介质”（建议用于更快的处理）
将ZIP文件保存到 data/ 目录

摄入数据

# Ingest all ZIP files from a directory
whatsapp-mcp-cli ingest data/

# Ingest a specific file
whatsapp-mcp-cli ingest data/WhatsApp\ Chat\ -\ John.zip

CLI命令

# View collection statistics
whatsapp-mcp-cli stats

# List all indexed conversations
whatsapp-mcp-cli list-chats

# Semantic search
whatsapp-mcp-cli search "vacation plans"

# Search with filters
whatsapp-mcp-cli search "birthday party" --chat-id john_doe --limit 20

# Drop all data (use with caution!)
whatsapp-mcp-cli drop --yes

运行MCP服务器

# Start with stdio transport (for Claude Desktop)
whatsapp-mcp

# Start with HTTP transport (for development/testing)
whatsapp-mcp --transport http --port 8000

Claude桌面集成

配置

将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/.venv/bin/whatsapp-mcp",
      "args": [],
      "env": {
        "MILVUS_HOST": "localhost",
        "MILVUS_PORT": "19530"
      }
    }
  }
}

替换 /path/to/whatsapp-mcp 安装的实际路径。

可用工具

配置后，Claude可以使用这些工具：

工具	说明
`semantic_search`	使用自然语言按含义查找消息
`search_by_date`	在特定日期范围内搜索
`search_by_sender`	按参与者筛选邮件
`list_chats`	查看所有可用对话
`get_chat_stats`	获取索引数据的统计信息

示例提示

“搜索我的WhatsApp消息，了解有关度假计划的讨论”
“查找2025年1月以来关于生日聚会的消息”
“约翰对项目截止日期说了什么？”
“显示我索引的所有对话”

环境变量

变量	默认值	描述
`MILVUS_HOST`	`localhost`	Milvus服务器主机名
`MILVUS_PORT`	`19530`	Milvus服务器端口

故障排除

Milvus连接失败

Failed to connect to Milvus: ...

解决方案：确保Docker容器正在运行：

docker compose ps
docker compose up -d

未找到任何消息

Collection Statistics: 0 entities

解决方案：获取您的WhatsApp导出：

whatsapp-mcp-cli ingest data/

首次搜索缓慢

当嵌入模型加载到内存中时，第一次搜索可能需要10-30秒。后续搜索要快得多。

内存问题

如果您在处理大型数据集时遇到内存问题：

在摄入过程中减少批量
确保Docker分配了足够的内存（建议4GB以上）

克劳德桌面未连接

验证中的路径 claude_desktop_config.json 是正确的
确保在命令中激活了虚拟环境
检查Claude Desktop日志是否有错误
配置更改后重新启动Claude Desktop

发展

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/

# Run type checker
mypy src/

项目结构

whatsapp-mcp/
├── src/whatsapp_mcp/
│   ├── __init__.py
│   ├── cli.py           # CLI commands
│   ├── embeddings.py    # Embedding service
│   ├── milvus_client.py # Vector database client
│   ├── models.py        # Data models
│   ├── parser.py        # WhatsApp export parser
│   └── server.py        # MCP server
├── data/                # WhatsApp exports (gitignored)
├── docs/                # Documentation
├── docker-compose.yml   # Infrastructure
└── pyproject.toml       # Project configuration

许可证

麻省理工学院