Whats App Bridge

WhatsApp桥

将Claude Code（或任何兼容MCP的AI）连接到WhatsApp-发送消息、反应、编辑、删除、监控组、按含义搜索、下载媒体、转录语音笔记等。

建筑

Claude Code  Python MCP Server  Go Bridge  WhatsApp
                           |                        |
                     semantic_search           PostgreSQL / SQLite
                           |                        |
                     pgvector (in PG)       Python Dashboard (read-only)
                                            (FastAPI + HTMX)

组件：

• Go Bridge -WhatsApp协议通过Whatsmow，REST API，速率限制，自动媒体下载，链接索引，语音笔记转录，遥测
• Python MCP服务器 -stdio上的17个MCP工具，多账户支持
• Python仪表板 -可选只读web UI（FastAPI+HTMX）
• Python嵌入器 -将消息嵌入pgvector进行语义搜索的后台工作器
• Python转录器 -通过Whisper转录语音笔记并重试的后台工作人员
• PostgreSQL+pgvector -内置矢量搜索的主数据库
• SQLite -单过程设置的轻量级替代方案（无矢量搜索）

快速开始

选项A:Docker（推荐）

git clone https://github.com/asimzeeshan/WhatsApp-bridge.git
cd WhatsApp-bridge
cp .env.example .env
cp config.example.toml config.toml
# Edit .env: set your POSTGRES_PASSWORD
# Edit config.toml: set bridge.database.driver = "postgres"

# Start core stack
docker compose up -d

# First-time QR scan
docker compose logs -f bridge
# Scan the QR code with WhatsApp > Settings > Linked Devices > Link a Device

# Optional: dashboard and whisper transcription
docker compose --profile dashboard --profile whisper up -d

服务已启动：

• 桥: http://127.0.0.1:8080
• PostgreSQL+pgvector: 127.0.0.1:5432
• 嵌入器：后台工作者（自动嵌入新消息）
• 转录器：后台工作者（自动转录语音笔记）
• 仪表盘 （可选）：http://127.0.0.1:9090

选项B：本机（macOS/Linux）

先决条件： 转到1.25+，Python 3.11+， 紫外线

git clone https://github.com/asimzeeshan/WhatsApp-bridge.git
cd WhatsApp-bridge
cp config.example.toml config.toml

首次运行（二维码扫描）：

make build-bridge
make run-bridge       # scan QR code, then Ctrl+C

运行所有内容：

make run-all          # bridge + dashboard in background
make status           # check running status
make stop-all         # stop everything

如果您的会话到期（约20天），请运行 make run-bridge 在前台扫描新的二维码。

连接克劳德代码

添加到您的 .mcp.json:

{
  "mcpServers": {
    "whatsapp-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/WhatsApp-bridge/mcp-server", "whatsapp-mcp"],
      "env": {
        "BRIDGE_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

多账户设置（可选）

为不同的WhatsApp帐户运行多个网桥实例：

./bin/whatsapp-bridge --config config.primary.toml    # port 8080
./bin/whatsapp-bridge --config config.secondary.toml  # port 8081 (read-only monitoring)

使用 BRIDGE_ACCOUNTS 而不是 BRIDGE_URL:

{
  "env": {
    "BRIDGE_ACCOUNTS": "[{\"name\":\"primary\",\"url\":\"http://127.0.0.1:8080\"},{\"name\":\"secondary\",\"url\":\"http://127.0.0.1:8081\",\"read_only\":true}]"
  }
}

所有MCP工具都接受可选 account 参数。只读帐户上的发送操作被阻止。

MCP工具（17）

特性

消息传递

• 文本、媒体、语音备忘 -发送和接收所有消息类型
• 表情符号反应 -发送和接收对消息的反应
• 消息编辑 -编辑已发送的消息（在WhatsApp的20分钟窗口内）
• 消息撤销 -删除所有人的邮件
• 引用和提及 -回复消息并@提及参与者

媒体

• 自动图像下载 -所有接收到的图像都保存到 media/images/YYYY-MM-DD/
• 自动音频下载 -所有收到的语音备忘均已保存至 media/audio/YYYY-MM-DD/
• 媒体下载API -按需下载任何媒体 download_media 工具或REST API
• MIME类型处理 -正确的文件扩展名，即使是参数化类型（例如。 audio/ogg; codecs=opus)
• 本地路径跟踪 -存储在转录管道数据库中的下载媒体路径

存储

• PostgreSQL+pgvector -具有并发访问和内置矢量搜索功能的生产数据库（推荐）
• SQLite -WAL模式的轻量级替代方案（单进程，无矢量搜索）
• 配置驱动：通过以下方式在SQLite和PostgreSQL之间切换 config.toml

智能

• 语义搜索 -使用pgvector余弦相似度按含义查找消息
• 多语言嵌入 - paraphrase-multilingual-MiniLM-L12-v2 型号（384个维度，50多种语言）
• 语音笔记转录 -通过Whisper自动进行WAV转换（支持Whisper.cpp和OpenAI兼容的API）
• 转录重试 -后台工作人员进行指数级回退，在丢失文件时重新下载
• 链接索引 -提取并分类URL（YouTube、GitHub、Twitter/X等）

运营

• 多账户 -支持只读的多个WhatsApp帐户
• 速率限制 -可配置的令牌桶，具有抖动功能，可防止禁令
• 遥测 -每日消息/媒体计数器，按工具呼叫跟踪
• 健康终点 -内存、磁盘、数据库大小、goroutine计数
• 仪表盘 -具有自动刷新状态的深色主题HTMX UI
• Docker部署 -具有Compose、健康检查和服务依赖关系的全栈
• macOS启动 -登录时自动启动，崩溃时自动重启

REST API

配置

凭据已生效 .env （复制自 .env.example).桥接设置 config.toml （复制自 config.example.toml).

[bridge]
addr = "127.0.0.1:8080"

[bridge.database]
driver = "postgres"  # or "sqlite"
# DSN set in .env as PG_DSN

[bridge.ratelimit]
messages_per_second = 0.5

[bridge.media]
auto_download_images = true
auto_download_audio = true
images_dir = "./media/images"
audio_dir = "./media/audio"

[bridge.transcription]
enabled = true
whisper_url = "http://127.0.0.1:8443/inference"
model = "large-v3-turbo"
language = ""  # empty = auto-detect

Docker服务

语音笔记转录

该桥支持通过两种方法自动转录语音笔记：

桥内转录

Go桥可以在语音笔记到达时在线转录。在中配置 config.toml:

[bridge.transcription]
enabled = true
whisper_url = "http://127.0.0.1:8443/inference"

独立转录工作者

为了更稳健地处理重试逻辑，请运行Python转录器worker：

cd transcriber
uv run whatsapp-transcriber --pg "$PG_DSN" --whisper "$WHISPER_URL"

工人：

• 轮询PostgreSQL以查找未转录的音频消息
• 使用将ogg/opus转换为WAV opusdec （首选）或 afconvert （macOS回退）
• 将WAV发送到whisper.cpp /inference 端点
• 当Whisper不可用时，以指数级回退进行重试
• 如果本地文件丢失，则通过桥接API重新下载音频

耳语后端

• whisper.cpp （原生）-使用 /inference 端点，需要WAV输入 temperature=0.0
• speaches ai （Docker）-OpenAI兼容API，位于 /v1/audio/transcriptions
• 任何与OpenAI兼容的Whisper API

禁令风险评估

此项目使用 怎么回事，一个反向工程的WhatsApp Web客户端。使用非官方API存在固有风险。

内置保护

建议

• 使用一个 次要电话号码，不是你的初选
• 保持现状 更新 (go get -u go.mau.fi/whatsmeow@latest)
• 保持消息音量 合理的 （自动发送的消息数\<200条/天）

安全

• 绑定到的HTTP API 仅127.0.0.1 （驾驶台和仪表板）
• 所有SQL查询都使用 参数化语句
• 下载目录上的路径遍历保护
• 通过chi中间件实施速率限制器
• 仪表板是 只读
• Docker容器以非root身份运行（UID 1000）

生成文件目标

项目结构

WhatsApp-bridge/
  bridge/            # Go bridge (whatsmeow + REST API)
    api/             #   HTTP handlers (send, download, status, health)
    client/          #   WhatsApp client wrapper (events, media download)
    config/          #   Configuration parsing
    media/           #   OGG analysis, Whisper transcription
    store/           #   Database layer (PostgreSQL + SQLite, migrations)
  mcp-server/        # Python MCP server (FastMCP, 16 tools)
  dashboard/         # Python dashboard (FastAPI + HTMX)
  embedder/          # Python embedding worker (sentence-transformers + pgvector)
  transcriber/       # Python transcription worker (Whisper + retry logic)
  scripts/           # Service install, migration scripts
  docs/              # Testing guide
  data/              # Runtime: DB, PID files (gitignored)
  logs/              # Runtime logs (gitignored)
  media/             # Downloaded images + audio (gitignored)
  docker-compose.yml # Full stack Docker deployment
  config.toml        # Runtime config (gitignored)
  Makefile           # Native build and run targets

CI/CD

A. 每天UTC凌晨3点运行，更新Go和Python依赖关系，构建、测试和打开PR（如果有任何更改）。

测试

看 docs/TEST.md 用于构建验证、安全审计结果、集成测试清单和已知限制。

免责声明

该项目通过whatsmow使用非官方的WhatsApp API。它没有得到WhatsApp或Meta的认可、附属或支持。使用风险自负。使用非官方API可能会违反WhatsApp的服务条款，并可能导致帐户限制。

作者

阿西姆·泽尚

许可证

麻省理工学院