Xây dựng máy chủ tìm kiếm tin nhắn WhatsApp riêng tư với whatsapp-mcp

whatsapp-mcp thực hiện những gì

whatsapp-mcp là một máy chủ nhỏ cho phép tác nhân AI tương thích với MCP đọc và tìm kiếm tin nhắn WhatsApp của bạn. Máy chủ chạy trong tài khoản Cloudflare của chính bạn và liên kết với điện thoại như một thiết bị được liên kết kiểu WhatsApp Web.

Sau khi thiết lập ban đầu, các ứng dụng như Claude Code, Claude Desktop hoặc những ứng dụng MCP khác có thể trả lời các câu hỏi như:

• Dana đã nói gì về các chuyến bay?
• Tìm mọi tin nhắn đề cập đến hợp đồng thuê trong tất cả cuộc trò chuyện.
• Tóm tắt những gì tôi đã bỏ lỡ trong nhóm gia đình tuần này.

Máy chủ được thiết kế chỉ để đọc: máy chủ có thể thu thập, tìm kiếm và hiển thị tin nhắn, nhưng không thể gửi tin nhắn WhatsApp.

Hệ thống hoạt động như thế nào

Điện thoại của bạn vẫn là nguồn dữ liệu chính xác duy nhất. Bản triển khai Cloudflare hoạt động như một thiết bị được liên kết và chỉ kết nối với WhatsApp khi cần đồng bộ dữ liệu hoặc khi bạn ghép nối tài khoản.

Khi tác nhân yêu cầu thông tin, máy chủ sẽ lấy các bản cập nhật đang chờ từ WhatsApp nếu bản sao được lưu trữ đã cũ hơn mười phút. Một lần lấy dữ liệu theo lịch cũng chạy mỗi ngày. Sau khi thu thập tin nhắn, máy chủ lại ngắt kết nối. Điện thoại của bạn vẫn hoạt động bình thường và tiếp tục nhận thông báo.

Tin nhắn được lưu trong cơ sở dữ liệu SQLite bên trong Cloudflare Durable Object thuộc tài khoản của bạn. Máy chủ không gửi lịch sử tin nhắn của bạn đến dịch vụ lưu trữ bên ngoài.

Điều kiện tiên quyết

Trước khi cài đặt, hãy chuẩn bị:

• Một tài khoản Cloudflare sử dụng gói Workers Paid.
• Node.js 20 trở lên.
• Một điện thoại có tài khoản WhatsApp bạn muốn liên kết.
• Một ứng dụng MCP, chẳng hạn như Claude Code hoặc Claude Desktop.

Gói Workers trả phí rất quan trọng vì việc nhập lịch sử WhatsApp lớn có thể vượt quá giới hạn CPU mặc định. Kho lưu trữ này tăng giới hạn đó trong wrangler.jsonc, và Cloudflare yêu cầu gói trả phí để sử dụng giới hạn cao hơn.

Cài đặt và triển khai

Sao chép kho lưu trữ, cài đặt các phần phụ thuộc, tạo namespace KV bắt buộc, lưu mật khẩu chủ sở hữu và triển khai Worker:

git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install

npx wrangler kv namespace create OAUTH_KV
npx wrangler secret put OWNER_PASSWORD
npm run deploy

Mật khẩu phải dài ít nhất 12 ký tự. Khi quá trình triển khai hoàn tất, Wrangler sẽ in ra một URL tương tự https://whatsapp-mcp.your-name.workers.dev. Mở URL đó để tiếp tục thiết lập.

Nếu muốn sử dụng tên miền tùy chỉnh, hãy làm theo các chú thích ở cuối wrangler.jsonc.

Liên kết tài khoản WhatsApp

Trang triển khai cung cấp các bước thiết lập còn lại.

1. Chọn tùy chọn liên kết WhatsApp.
2. Mở WhatsApp trên điện thoại, vào Cài đặt, Thiết bị đã liên kết rồi chọn Liên kết thiết bị.
3. Quét mã QR do máy chủ hiển thị. Nếu đang dùng cùng điện thoại đó và không thể quét màn hình của điện thoại, hãy sử dụng tùy chọn ghép nối bằng số điện thoại.
4. Chờ trong khi lần liên kết đầu tiên nhập lịch sử mà WhatsApp cung cấp cho thiết bị mới.

Trang này hiển thị tiến độ nhập và bạn có thể đóng trang trong khi quá trình vẫn tiếp tục. Lần nhập ban đầu có thể không bao gồm mọi tin nhắn trong lịch sử vì WhatsApp quyết định lịch sử nào sẽ được cung cấp cho thiết bị mới được liên kết.

Kết nối ứng dụng MCP

Trong Claude Code, đăng ký máy chủ đã triển khai bằng endpoint /mcp:

claude mcp add --transport http whatsapp https://your-url/mcp

Sau đó chạy /mcp trong Claude Code và đăng nhập bằng mật khẩu chủ sở hữu. Các ứng dụng MCP khác cũng nên được cấu hình bằng cùng URL:

https://your-url/mcp

Sau khi xác thực, hãy yêu cầu tác nhân liệt kê cuộc trò chuyện, lấy tin nhắn hoặc tìm kiếm lịch sử của bạn.

Sử dụng các công cụ có sẵn

Máy chủ MCP cung cấp các công cụ chuyên dụng để đọc và duy trì bản sao tin nhắn cục bộ:

• list_chats liệt kê các cuộc trò chuyện, mới nhất trước, với tùy chọn lọc theo tên hoặc số điện thoại.
• get_messages đọc tin nhắn từ một cuộc trò chuyện và hỗ trợ phân trang lùi hoặc tiến theo ngày.
• search_messages thực hiện tìm kiếm toàn văn trong tất cả cuộc trò chuyện hoặc trong một cuộc trò chuyện được chọn.
• unnamed_chats tìm các cuộc trò chuyện chỉ được nhận diện bằng số điện thoại, ưu tiên những cuộc trò chuyện có nhiều hoạt động nhất và hiển thị tin nhắn mới nhất từ người bên kia.
• set_contact_names lưu tên cho các số điện thoại để tên cũng có thể hiển thị chính xác trong các cuộc trò chuyện nhóm.
• sync_now lấy tin nhắn mới ngay lập tức.
• link_status cho biết tài khoản đã được liên kết hay chưa, lần đồng bộ gần nhất và lượng dữ liệu đang được lưu trữ.
• relink xóa liên kết hiện tại và bắt đầu lại quá trình ghép nối. Các tin nhắn đã lưu vẫn khả dụng.

Các công cụ đọc sẽ tự động đồng bộ trước khi bản sao được lưu trữ đã cũ hơn mười phút. Vì vậy, bạn có thể sử dụng yêu cầu bằng ngôn ngữ tự nhiên mà không cần gọi thủ công sync_now cho từng truy vấn.

Xử lý các cuộc trò chuyện chỉ hiển thị số điện thoại

Một số cuộc trò chuyện hiển thị dưới dạng số điện thoại vì WhatsApp không cung cấp tên liên hệ cho mọi thiết bị được liên kết. Điều này thường xảy ra với các cuộc trò chuyện một lần hoặc những người chưa được lưu trong danh bạ WhatsApp của bạn.

Hãy yêu cầu tác nhân:

Find names for my unnamed chats.

Tác nhân có thể gọi unnamed_chats, đối chiếu các số với một tích hợp danh bạ mà tác nhân đã có, rồi gửi các kết quả khớp thông qua set_contact_names. Ví dụ: trình kết nối Google Contacts hoặc Gmail có thể cung cấp tên tương ứng. Bản thân máy chủ không đăng nhập vào dịch vụ danh bạ.

Tên đã lưu được liên kết với số điện thoại và do đó cũng có thể được sử dụng trong các cuộc trò chuyện nhóm. Một số số điện thoại sẽ vẫn không có tên khi không tồn tại liên hệ tương ứng.

Hiểu về lịch sử phương tiện và tin nhắn

Các tệp phương tiện không được tải xuống. Hình ảnh, tin nhắn thoại và tài liệu được biểu thị bằng các nhãn như [image] hoặc [voice note 12s]. Chú thích được giữ lại khi WhatsApp cung cấp, nhưng tin nhắn thoại không được chuyển thành văn bản.

Lần liên kết đầu tiên sẽ nhập mọi lịch sử mà WhatsApp chọn gửi. Lịch sử thường được gửi một lần cho mỗi liên kết. Nếu quá trình nhập chưa đầy đủ, việc liên kết lại có thể yêu cầu nhập thêm trong khi vẫn giữ các tin nhắn đã lưu. Quy trình tiếp nhận được thiết kế để có tính lũy đẳng, vì vậy việc nhập lại không chủ ý tạo các bản ghi trùng lặp.

Liên kết lại tài khoản

Hãy liên kết lại nếu WhatsApp báo rằng thiết bị đã bị gỡ hoặc nếu bạn muốn bắt đầu lại quy trình ghép nối. Yêu cầu agent chạy relink, hoặc mở /setup rồi chọn Hủy liên kết và quét lại.

Quét mã QR mới khi được nhắc. Các tin nhắn đã lưu vẫn được giữ nguyên, trong khi liên kết mới có thể bổ sung lịch sử còn thiếu.

Cấu hình nâng cao

Triển khai mặc định sử dụng xác thực bằng mật khẩu. Các giá trị cấu hình chính gồm:

• OWNER_PASSWORD: mật khẩu chủ sở hữu, có độ dài tối thiểu 12 ký tự.
• OWNER_EMAIL: địa chỉ email duy nhất được phép khi sử dụng chế độ dịch vụ đăng nhập.
• OPERATOR_NAME: tên tùy chọn được hiển thị trên trang quyền riêng tư.
• DEFAULT_COUNTRY_CODE: mã quốc gia chỉ gồm chữ số, được sử dụng khi agent lưu một số điện thoại chưa có mã quốc gia.
• LOGIN_ORIGIN: chuyển triển khai sang chế độ dịch vụ đăng nhập.
• ALLOWED_ORIGINS: các origin được chấp nhận cho token của dịch vụ đăng nhập.
• PIN: giá trị tùy chọn dài từ 32 ký tự, cho phép truy cập các route gỡ lỗi được bảo vệ thông qua header x-pin.
• OAUTH_KV và WA: các binding KV và Durable Object được ứng dụng sử dụng.

Giữ các giá trị riêng cho từng triển khai như domain, KV ID và email trong tệp wrangler.local.jsonc được gitignore. Triển khai cấu hình cục bộ bằng:

npm run deploy:local

Gỡ lỗi sự cố đồng bộ hóa

Nếu cấu hình PIN, máy chủ sẽ cung cấp các endpoint chẩn đoán được bảo vệ. Gửi PIN trong header x-pin:

• /debug hiển thị giai đoạn phiên, trạng thái liên kết, số lượng và các sự kiện phiên gần đây.
• /debug/pull bắt đầu đồng bộ hóa ngay lập tức.
• /debug/chats?q=, /debug/messages?chat=, /debug/search?q= và /debug/types kiểm tra dữ liệu đã lưu.
• /debug/unnamed hiển thị các cuộc trò chuyện do unnamed_chats trả về.
• /debug/sql?q= chạy một truy vấn SELECT chỉ đọc trên kho lưu trữ.
• /debug/logout thực hiện thao tác tương đương với việc liên kết lại.

Sau khi triển khai thành công, trình tự xác minh hữu ích là kiểm tra để /debug báo phiên đang ở trạng thái nhàn rỗi và tài khoản đã liên kết, chạy /debug/pull, sau đó kiểm tra việc liệt kê cuộc trò chuyện, lấy tin nhắn, tìm kiếm toàn văn, xử lý cuộc trò chuyện không tên và đặt tên liên hệ.

Phát triển cục bộ

Để phát triển cục bộ, hãy tạo tệp .dev.vars chứa một mật khẩu đủ dài và khởi động Worker:

OWNER_PASSWORD=your-12-character-or-longer-password

npm run dev

Phát triển cục bộ sử dụng một Durable Object riêng với bộ nhớ trống. Bạn có thể kiểm tra quy trình đăng nhập và hiển thị mã QR thực, nhưng việc liên kết điện thoại cục bộ sẽ tạo thêm một thiết bị được liên kết.

Trước khi gửi các thay đổi mã, hãy chạy:

npm run typecheck
npm test

Bộ kiểm thử chạy mã kho lưu trữ trên SQLite tích hợp sẵn của Node, với Node 22.13 trở lên. Tìm kiếm toàn văn không được môi trường SQLite đó hỗ trợ, vì vậy hãy kiểm thử tìm kiếm sau khi triển khai.

Các cân nhắc quan trọng về bảo mật và nền tảng

Dự án này không phải là tích hợp WhatsApp chính thức. WhatsApp không cung cấp API để đọc tin nhắn cá nhân, và dự án này sử dụng cùng giao thức với WhatsApp Web thông qua thư viện Baileys mã nguồn mở. Việc sử dụng này có thể vi phạm điều khoản của WhatsApp. Chỉ sử dụng với tài khoản của bạn, đồng thời nhớ rằng rủi ro thực tế thấp đối với một thiết bị được liên kết chỉ đọc nhưng không phải bằng không.

Một triển khai được thiết kế cho một người và một tài khoản WhatsApp. Mỗi triển khai lưu trữ toàn bộ lịch sử tin nhắn và thông tin đăng nhập tài khoản đang hoạt động, vì vậy người dùng nên chạy các triển khai riêng thay vì dùng chung một triển khai.

Tin nhắn vẫn nằm trong bộ nhớ SQLite của Durable Object, nhưng bất kỳ ai có quyền truy cập vào thông tin xác thực triển khai hoặc xác thực chủ sở hữu đều có thể truy cập lịch sử đã lưu. Hãy bảo vệ cẩn thận mật khẩu, tài khoản Cloudflare, các secret và mọi PIN gỡ lỗi.

Kết luận

whatsapp-mcp cung cấp cầu nối thực tế giữa giao thức thiết bị được liên kết của WhatsApp và các client MCP. Hãy triển khai lên Cloudflare, liên kết điện thoại một lần, kết nối agent với /mcp, rồi sử dụng các công cụ như search_messages, get_messages và set_contact_names để khám phá kho lưu trữ tin nhắn của chính bạn. Thiết kế chỉ đọc, bộ nhớ Durable Object riêng tư, cơ chế đồng bộ theo lịch và quy trình liên kết lại rõ ràng khiến công cụ phù hợp để tìm kiếm tin nhắn cá nhân trong khi vẫn giữ quyền kiểm soát triển khai.