Skip to main content
Glama

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 computer

How 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

whatskept init [dir]

Create a workspace.

whatskept import <backup>

Import full history from an encrypted iPhone backup. Resumable. --list finds backups.

whatskept enrich

Turn queued photos, voice notes, videos and PDFs into text via OpenRouter. Resumable.

whatskept live

Link as a WhatsApp companion device (scan a QR once) and capture new messages.

whatskept send <chat> <text>

Send through the running live. Supports --reply-to and --forward.

whatskept mcp --database <file>

Serve the database over MCP at /mcp, behind a bearer token.

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/whatskept

Real 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 scenarios

Contributing

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

MIT

Available Tools

4 tools
get_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

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

    A4.2/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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.
      2
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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.
      423
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT