google-keep-mcp

A small, read-only Model Context Protocol (MCP) server that lets an AI assistant (OpenAI Codex, Claude, or any MCP client) search and read your Google Keep notes from a Google Takeout export.

Unofficial. This project is not affiliated with, endorsed by, or supported by Google LLC. "Google Keep" and "Google Takeout" are trademarks of Google LLC. This tool only reads data you export or you authorize. It never creates, edits, or deletes notes.

What it does

• Imports a Google Keep Takeout export (.zip or extracted folder) into a local, normalized index stored under your home directory.
• Exposes MCP tools to search, list, read, get recent, and show stats for those notes.
• Runs fully local. Your notes never leave your machine.

The primary, supported path is Takeout import. A live read-only Google Keep API sync also exists but is advanced / experimental — see Advanced: live OAuth sync.

Requirements

• Node.js >= 20
• A Google Keep Takeout export — see docs/TAKEOUT.md

Install & configure

The server is distributed on npm and launched via npx — no global install needed.

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.google-keep]
command = "npx"
args = ["-y", "@piterskiy/google-keep-mcp"]

Full walkthrough: docs/INSTALL_CODEX.md.

Claude (Claude Code / Claude Desktop)

Claude Code CLI:

claude mcp add google-keep -- npx -y @piterskiy/google-keep-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-keep": {
      "command": "npx",
      "args": ["-y", "@piterskiy/google-keep-mcp"]
    }
  }
}

Full walkthrough: docs/INSTALL_CLAUDE.md.

Quick start

1. Create a Google Takeout export that includes Keep (docs/TAKEOUT.md).
2. Configure the server in your MCP client (above).
3. Ask the assistant to import and then read your notes, e.g.:
   • "Import my Google Keep Takeout export at ~/Downloads/takeout-keep.zip."
   • "Find my Keep notes about invoices."
   • "Show my 5 most recent Keep notes."

MCP tools

| Tool | Purpose | | --- | --- | | keep_import_takeout | Import a Takeout .zip or extracted folder into the local index | | keep_search_notes | Search notes by title / text / labels | | keep_list_notes | List notes, optionally filtered by label / archived / trashed | | keep_get_note | Read one note by id | | keep_recent | List recently updated notes | | keep_stats | Show index metadata (counts, labels, active source) | | keep_oauth_configure | (advanced) Store your own Google OAuth client | | keep_oauth_start | (advanced) Start the local OAuth consent flow | | keep_oauth_status | (advanced) Show OAuth configuration/authorization state | | keep_sync_live | (advanced) Fetch notes via the official read-only Keep API |

Data & privacy

• The normalized index is stored at ~/.codex/plugin-data/google-keep/ by default. Override the base directory with the CODEX_HOME environment variable.
• No note content, OAuth token, or telemetry is ever sent anywhere by this server. The only outbound network call exists solely in the optional live-sync path and goes directly to Google's own API with a read-only scope.
• See PRIVACY.md and SECURITY.md.

Advanced: live OAuth sync (experimental)

keep_sync_live can pull notes through the official read-only Google Keep API (https://www.googleapis.com/auth/keep.readonly) instead of Takeout. This is experimental and intentionally not the recommended path because:

• Each user must create their own Google Cloud OAuth desktop client.
• The Google Keep API is a Workspace/enterprise API; on consumer @gmail.com accounts the call commonly fails (403 / SERVICE_DISABLED / scope-gated).
• The API does not return labels, pinned, archived, or color metadata.

If you still want it, see docs/INSTALL_CODEX.md → Advanced.

Development

npm ci
npm test          # vitest suite
node --check ./mcp/server.mjs
npm run mcp       # run the MCP server over stdio

See CONTRIBUTING.md.

License

MIT © kostyaff