WhatsKept
Turns WhatsApp history and new messages into a searchable local database, including text extracted from photos, voice notes, videos, and PDFs, and lets an AI agent search chats, send messages, reply, forward, and act on conversations from the user's account.
What is WhatsKept?
WhatsKept turns your WhatsApp, years of history plus every new message, into one searchable database on your machine, including what's inside photos, voice notes, videos and PDFs. Over MCP, your AI agent can search it and message from your account:
"What did the plumber quote for the bathroom? It might be in a voice note."
"Forward the boarding passes from the travel group to my brother."
"Reply to the school's trip message: count us in."
"Find a date that works for the book club, then send everyone the invite."
"Chase everyone who still owes for the birthday gift until they've all paid."
Related MCP server: steno-personal
Audit
Not sure you can trust it? Have your agent check first:
trace the latest release of https://github.com/alkait/whatskept to the source commit it
was built from and audit that code: should I trust this with my privacy and my WhatsApp data?Installation
WhatsKept is installed and operated by your AI agent. Paste this into Claude Code:
install the latest release of https://github.com/alkait/whatskept and put it on my PATH.
When done, ask me one question β where my workspace is, or where I'd like a new one β
then tell me to continue in a new terminal and print the matching command with my path
filled in:
New workspace: mkdir -p <path> && cd <path> && whatskept init && claude "Hi"
Existing workspace: cd <path> && claude "Hi"Say "Hi" in the new terminal, and the agent walks you through the rest: importing your backup, enriching media, live capture and connecting your AI client π
Uninstall
uninstall WhatsKept from my computerHow it works
WhatsKept is a single binary. Everything lives in a workspace: a folder
created by whatskept init, holding the database, a .whatskept/ settings
folder and a guide (AGENTS.md) that teaches your agent to operate it. Live
capture and sending use whatsmeow, which
links WhatsKept to your account as a companion device, the same way WhatsApp
Web does.
Command | What it does |
| Create a workspace. |
| Import full history from an encrypted iPhone backup. Resumable. |
| Turn queued photos, voice notes, videos and PDFs into text via OpenRouter. Resumable. |
| Link as a WhatsApp companion device (scan a QR once) and capture new messages. |
| Send through the running |
| Serve the database over MCP at |
Privacy & security
Concern | How WhatsKept handles it | Your responsibility |
Where does my data live? | In one SQLite file in your workspace, on your computer or a server you run. There is no WhatsKept service, account or telemetry. | Keep that machine secure. |
Who gets my photos, videos, voice notes and PDFs? | OpenRouter, only when you enrich. Media goes out, text comes back, and the local file is deleted. | Decide whether OpenRouter is acceptable for your media. If not, don't enrich. |
What does my AI provider see? | Only what your agent reads through MCP. | Use an AI provider you trust with your chats. |
Who can reach the MCP server? | Only requests carrying your bearer token. | Keep the token secret. |
Can I trust the binary? | Every release is built by GitHub Actions from a public commit. | Run the Audit prompt before you install, or build it yourself from source. |
Development
go test ./... # everything; no phone, key or network needed
go build -o whatskept ./cmd/whatskeptReal end-to-end tests run against a second WhatsApp number and are gated
behind the e2e build tag:
go run ./cmd/whatsapp-tester pair # one-time: pair the tester number
go test -tags e2e ./e2e-test -workspace <dir> # with `whatskept live` running there
go test -tags e2e ./e2e-test -workspace <dir> -enrich # also the paid enrichment scenariosContributing
Issues and ideas are welcome. Before a pull request, open an issue so we can
agree on the change. Keep it small, and keep go test ./... green.
License
Available Tools
4 toolsget_schemaA
Return the database schema: every CREATE TABLE / CREATE VIEW / CREATE VIRTUAL TABLE statement. Call this once before writing SQL β the views (v_messages, v_chats, messages_fts, ...) are the intended query surface.
Returns: schema
queryA
Run a read-only SQL statement against the WhatsApp workspace database and return rows as JSON. Writes are blocked at the connection level. Always aggregate or LIMIT; results are capped at 500 rows.
Inputs: sql (required), limit. Returns: rows, columns, truncated
searchA
Full-text search across ALL surfaces β typed messages, image OCR and descriptions, voice-note transcripts, document filenames and PDF body text. FTS5 syntax: "exact phrase", AND, OR, NOT, NEAR/3, prefix*. Use this first for any 'did anyone mention X' question; fall back to query for joins and aggregates.
Inputs: query (required), limit. Returns: hits
sendA
Send a WhatsApp text message from the user's own account, or forward one. to is a phone number in international format or a chat JID (v_chats.jid β the only way to address a group). Optional reply_to is the v_messages.stanza_id of a message in that chat to quote. To forward instead, give forward (a v_messages.stanza_id from any chat: text, link, image, video, GIF, sticker, voice note or document) and no text. Irreversible and seen by real people: send only what the user explicitly asked for, to the chat they named. Needs whatskept live running.
Inputs: to (required), text, forward, reply_to. Returns: id, ts, chat, warning
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 4 tools
The tools have mostly distinct purposes: get_schema introspects structure, query runs SQL, search performs full-text lookup, and send writes outbound messages. query and search overlap somewhat, but the descriptions explicitly guide when to use search first versus query for joins/aggregates.
All names are lowercase and readable, with three single-verb names (query, search, send) and one verb_noun name (get_schema). This is a minor deviation from a uniform pattern rather than an inconsistent convention.
Four tools is well-scoped for a WhatsApp workspace database server: schema discovery, SQL querying, full-text search, and message sending. Each tool has a clear role and the set avoids unnecessary surface area.
The read side is well covered through get_schema, query, and search, and outbound messaging covers text sending and forwarding. Minor gaps remain around sending new media/attachments or richer message actions, but core workflows are covered and query provides a workaround for many read needs.
Maintenance
Related MCP Connectors
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
Your WhatsApp history in Claude and ChatGPT: search years of chats, voice notes transcribed.
iMessage for AI agents, from your iPhone. No Mac needed, and you choose which chats they read.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with your personal WhatsApp account to search messages, list chats, and send messages. It stores all authentication and message data locally using SQLite for privacy and direct multi-device API connection.1ISC
- AlicenseNot gradedqualityBmaintenanceLets AI agents search and read your personal Telegram and WhatsApp conversations through a self-hosted, read-only MCP server backed by a single SQLite file.2AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceLets an AI agent search and read your own WhatsApp chats from a self-hosted Cloudflare Worker, with full-text search across all messages, per-chat paging, and the ability to save contact names for numbers that appear unnamed. It is read-only, so it can never send messages on your behalf.423MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and read locally stored chat history, look up contacts, send messages and attachments, and retrieve media through a self-hosted local daemon with encrypted SQLite storage.1MIT