google-keep-mcp

An MCP server for Google Keep, built on gkeepapi (an unofficial, reverse-engineered client — there is no official Google Keep API for consumer accounts).

Tools

16 tools across three groups:

Notes & lists — search_notes, get_note, create_note, create_list, update_note, trash_note, restore_note, delete_note

Checklist items — add_list_item, update_list_item, delete_list_item

Labels — list_labels, create_label, delete_label, add_label_to_note, remove_label_from_note

Auth

gkeepapi authenticates with an email + master token (not your Google password, not an app password long-term). Get one:

uv run python scripts/get_master_token.py

This trades a Google App Password (requires 2FA on the account) for a master token via gpsoauth, one time. It also pins a random device ID so the server doesn't rely on the host machine's MAC address for its device identity — needed since this runs in a container, not on a fixed physical device.

Required env vars:

GOOGLE_KEEP_EMAIL=you@gmail.com
GOOGLE_KEEP_MASTER_TOKEN=...
GOOGLE_KEEP_DEVICE_ID=...

# optional: cache Keep state to disk for faster startup
GOOGLE_KEEP_STATE_PATH=./.keep_state.json

See .env.example.

Quick Start

uv sync

# Run locally (stdio)
uv run python -m google_keep_mcp.server

# Run as HTTP server
uv run python -m google_keep_mcp.server --transport streamable-http --host 0.0.0.0 --port 8080

Docker

Pre-built multi-arch images (amd64/arm64) are published to GHCR on every push to main:

docker pull ghcr.io/suckerfish/google_keep_mcp:latest

Or docker compose up using compose.yaml. Health check at GET /health.

Deployment

Runs on ampere via Komodo (stack: google-keep-mcp-ampere), registered in MetaMCP's main-namespace as google-keep-mcp (port 8082). Credentials are injected via Komodo secret variables ([[GOOGLE_KEEP_EMAIL]], [[GOOGLE_KEEP_MASTER_TOKEN]], [[GOOGLE_KEEP_DEVICE_ID]]) — never stored in the stack config or this repo. GOOGLE_KEEP_STATE_PATH points at a mounted volume so the Keep state cache survives container restarts.

Pushing to main rebuilds the image; redeploy the stack via Komodo to pick it up (auto_pull: true, but a fresh deploy still needs to be triggered — it doesn't auto-redeploy on push).

A note on stability

gkeepapi is unofficial and periodically breaks when Google changes its login flow or adds new Keep content types — see its CHANGELOG and issue tracker. If this server suddenly starts failing with LoginException or similar, it's very likely a gkeepapi compatibility issue, not something wrong in this repo. Check upstream before debugging locally.

Tech Stack

Component	Choice
MCP framework	FastMCP 2.x
Keep client	gkeepapi
Package management	uv