by feuerdev
Provides a command‑line and streamable‑HTTP MCP server that talks to Google Keep via the unofficial gkeepapi, exposing a rich set of tools for reading, creating, updating, labeling, collaborating on, and downloading media from Keep notes and checklists.
Keeps a programmatic interface to Google Keep available through the Model Context Protocol (MCP). It runs as a standard MCP server (STDIO by default or streamable‑HTTP) and offers a collection of CLI‑style tools that agents can invoke to query notes, manage checklists, modify note state, handle labels, collaborators and media.
GOOGLE_EMAIL: the Google account used for Keep.GOOGLE_MASTER_TOKEN: a master token obtained via the browser‑assisted flow described in the README.UNSAFE_MODE to allow modifications of notes that do not carry the keep-mcp label./mcp).Example JSON configuration for an MCP client:
{
"mcpServers": {
"keep-mcp-pipx": {
"command": "pipx",
"args": ["run", "keep-mcp"],
"env": {
"GOOGLE_EMAIL": "you@example.com",
"GOOGLE_MASTER_TOKEN": "aas_et/...",
"UNSAFE_MODE": "false"
}
}
}
}
find, get_note with filters for labels, colors, pinned/archived status, date ranges and result limits.create_note, create_list, update_note, checklist item manipulation (add_list_item, update_list_item, delete_list_item, move_list_item, reorder_list_items, replace_list_items).keep-mcp label) can be mutated; set UNSAFE_MODE=true to bypass.--transport streamable-http).How do I obtain a Google master token?
Follow the browser‑assisted flow: sign in at https://accounts.google.com/EmbeddedSetup, copy the oauth_token cookie, then exchange it with gpsoauth (via Docker or a local uv installation). The resulting token starts with aas_et/.
What does UNSAFE_MODE do?
When set to true the server removes the restriction that only notes bearing the keep-mcp label can be modified, allowing any note in the account to be changed.
Can I run Keep Mcp over HTTP?
Yes, start the server with keep-mcp --transport streamable-http (default host 127.0.0.1, port 8000). For external access place an authenticating reverse proxy in front.
Is there a Docker image?
A Dockerfile is provided. Build with docker build -t keep-mcp . and run with the required env vars, exposing only localhost unless you add a proxy.
Which Python version is required?
The project targets Python 3.11 (as indicated in the uv commands) and works with later 3.x versions.
Will the server modify notes created outside of Keep Mcp?
Only when UNSAFE_MODE is enabled; otherwise it refuses to mutate notes that lack the keep-mcp label.
MCP server for Google Keep
See CONTRIBUTING.md for contribution guidelines and required visual evidence.
"mcpServers": {
"keep-mcp-pipx": {
"command": "pipx",
"args": [
"run",
"keep-mcp"
],
"env": {
"GOOGLE_EMAIL": "Your Google Email",
"GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
}
}
}
Or with uvx:
"mcpServers": {
"keep-mcp": {
"command": "uvx",
"args": [
"keep-mcp"
],
"env": {
"GOOGLE_EMAIL": "Your Google Email",
"GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
}
}
}
GOOGLE_EMAIL: Your Google account email addressGOOGLE_MASTER_TOKEN: Your Google account master tokenkeep-mcp uses gkeepapi, which connects to Google Keep through an unofficial private API. A Google master token has full access to your account. Treat it like a password and never commit or share it.
You need Docker and a desktop browser.
Open https://accounts.google.com/EmbeddedSetup and sign in with the Google account you use for Keep.
Click I agree. The page may keep loading forever. Leave it open and continue.
Copy the oauth_token cookie:
https://accounts.google.com.https://accounts.google.com.Find the row named oauth_token and copy its value. It starts with oauth2_4/.
Right away, run this in a terminal and paste your email and the cookie value when asked:
docker run --rm -it ghcr.io/astral-sh/uv:python3.13-bookworm-slim uv run --no-project --with gpsoauth python -c "import gpsoauth; r = gpsoauth.exchange_token(input('Email: '), input('oauth_token: '), '0123456789abcdef'); print(r.get('Token', r))"
Without Docker, install uv and run the same command without the docker run --rm -it ghcr.io/astral-sh/uv:python3.13-bookworm-slim part.
The command prints your master token. It starts with aas_et/. Use it as GOOGLE_MASTER_TOKEN.
If it prints an error such as BadAuthentication instead, the cookie has expired. Repeat steps 1 to 4 to get a fresh one.
gpsoauth's alternative flow describes the token exchange.Older instructions may ask for your Google password or an app password and call perform_master_login(). That flow is unreliable and can return BadAuthentication. Use the browser-assisted flow above instead.
find: Search notes (case-insensitive by default) with optional filters for labels, colors, pinned, archived, trashed, creation/update date ranges (ISO 8601, UTC), and a result limit (default 50)get_note: Get a single note by IDcreate_note: Create a new note with title and text (automatically adds keep-mcp label)create_list: Create a checklist noteupdate_note: Update a note's title and textadd_list_item: Add an item to a checklist noteupdate_list_item: Update checklist item text and checked statedelete_list_item: Delete a checklist itemmove_list_item: Move an item to a zero-based final positionreorder_list_items: Bulk reorder a checklist using all its item IDsreplace_list_items: Replace the entire checklist, creating new item IDsGet the current item IDs and order with get_note. move_list_item takes
note_id, item_id, and position: 0 means first, and the last valid position
is the item count minus one. The position is the item's final index after moving.
For bulk ordering, call reorder_list_items with note_id and item_ids in the
desired first-to-last order. Supply every current item ID exactly once, including
checked items. Missing, duplicate, unknown, foreign, or deleted IDs are rejected
before mutation. Ordering preserves item IDs, text and checked states. Positions
refer to the combined order returned by get_note; Keep may display checked items
in a separate section according to its settings.
Example tool arguments (substitute IDs returned by get_note):
{"note_id":"NOTE_ID","item_id":"THIRD_ITEM_ID","position":0}
{"note_id":"NOTE_ID","item_ids":["THIRD_ITEM_ID","FIRST_ITEM_ID","SECOND_ITEM_ID"]}
replace_list_items takes note_id and an items array. Each item requires
text; checked is optional and defaults to false. Only these two item fields
are accepted. The full payload is validated before any item is changed. All old
items are marked for deletion and new items are created in input order with new
IDs. The note itself, title, labels, collaborators and other note metadata remain.
Passing items: [] clears the checklist; an empty bulk order is valid only for an
already empty checklist.
{"note_id":"NOTE_ID","items":[{"text":"Milk","checked":false},{"text":"Bread","checked":true}]}
All three tools currently require flat checklists: an existing checklist with
indented items is rejected without changes, so hierarchy cannot be silently lost.
They are annotated as destructive because ordering overwrites the existing order
and replacement deletes the old items.
They use the same keep-mcp label / UNSAFE_MODE restriction as other modification
tools. They refresh through the shared client, then sync once after mutation.
Moving an item to its current position or supplying the current bulk order leaves
the items untouched and skips the post-mutation sync.
This is not a server-side atomic transaction: a network failure can leave the
remote outcome uncertain. Read the note again before retrying, particularly after
replacement. Concurrent external edits can also affect the final order.
set_note_color: Set a note color (valid values: DEFAULT, RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN, PURPLE, PINK, BROWN, GRAY)pin_note: Pin or unpin a notearchive_note: Archive or unarchive a notetrash_note: Move a note to trashrestore_note: Restore a trashed/deleted notedelete_note: Mark a note for deletionlist_labels: List labelscreate_label: Create a labeldelete_label: Delete a labeladd_label_to_note: Add a label to a noteremove_label_from_note: Remove a label from a notelist_note_collaborators: List collaborator emails for a noteadd_note_collaborator: Add a collaborator email to a noteremove_note_collaborator: Remove a collaborator email from a notelist_note_media: List media blobs for a note (with media links)download_media: Download a note's media (images, drawings, audio) to a local directory through the authenticated session (the raw media links answer 403 to plain HTTP clients). Not available over Streamable HTTP, where the files would land on the serverBy default, all destructive and modification operations are restricted to notes that have were created by the MCP server (i.e. have the keep-mcp label). Set UNSAFE_MODE to true to bypass this restriction.
"env": {
...
"UNSAFE_MODE": "true"
}
If you prefer a JS-style workflow (npm i, npm start), use the included Makefile:
make install # like npm i
make start # like npm start
make test
make lint
Run the real-account smoke test with credentials:
GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smoke
Equivalent direct uv commands (without make):
UV_CACHE_DIR=/tmp/uv-cache uv venv --python 3.11 .venv
UV_CACHE_DIR=/tmp/uv-cache uv pip install --python .venv/bin/python -e .
UV_CACHE_DIR=/tmp/uv-cache uv run --no-sync --python .venv/bin/python -m server
The project includes a lightweight unit test suite under tests/.
It validates:
keep-mcp label requirement and UNSAFE_MODE=true override)src/server/cli.py using mocked Keep client objects (tool happy paths and key error paths)Run locally:
make test
For additional confidence, run a basic lifecycle smoke test against a dedicated test account:
GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smoke
What it does:
This script is intended for manual verification and is not run in CI.
GitHub Actions runs on every pull request and executes:
ruff check .)pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70)python -m compileall src)main (GitHub Actions)This repo includes a release workflow at .github/workflows/release.yml that runs on every push to main (including merged PRs).
It will:
vX.Y.Z)dist/*v<computed-version> with generated notesVersion bump rules:
! (example: feat!: or fix(api)!:) or commit body containing BREAKING CHANGEfeat:fix:, perf:, revert:docs:, chore:, ci:, test:, refactor: (unless the commit is marked as breaking)Required repository secret:
PYPI_API_TOKEN: a PyPI API token (recommended scope: this project only)To publish manually to PyPI:
pyproject.tomlpipx run build
pipx run twine upload --repository pypi dist/*
This is useful when you want a client to run this server from your local checkout instead of PyPI.
cd /ABSOLUTE/PATH/TO/keep-mcp
make install
config.toml clients (Codex, Goose, etc.)[mcp_servers.keep_mcp]
command = "make"
args = ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"]
[mcp_servers.keep_mcp.env]
GOOGLE_EMAIL = "you@example.com"
GOOGLE_MASTER_TOKEN = "your-master-token"
UNSAFE_MODE = "false"
mcpServers clients (Claude Desktop, Cursor, Cline, etc.){
"mcpServers": {
"keep-mcp-local": {
"command": "make",
"args": ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"],
"env": {
"GOOGLE_EMAIL": "you@example.com",
"GOOGLE_MASTER_TOKEN": "your-master-token",
"UNSAFE_MODE": "false"
}
}
}
}
Alternative (without make):
[mcp_servers.keep_mcp]
command = "uv"
args = [
"--directory", "/ABSOLUTE/PATH/TO/keep-mcp",
"run", "--no-sync", "--python", ".venv/bin/python",
"-m", "server"
]
Notes:
make install once before starting from an MCP client./.venv/bin/python path).make and uv are in your PATH.UNSAFE_MODE is optional; keep it "false" unless you explicitly want to modify non-keep-mcp notes.keep-mcp supports the MCP Streamable HTTP transport (/mcp endpoint) in addition to the default stdio transport:
# Start Streamable HTTP server on localhost (default: 127.0.0.1:8000)
keep-mcp --transport streamable-http
# Customize host or port
keep-mcp --transport streamable-http --host 127.0.0.1 --port 8000
[!NOTE]
keep-mcpbinds to127.0.0.1by default with DNS rebinding protection enabled. To expose the server to remote or web clients (such as Gemini web), place an authenticating proxy (such as mcp-auth-proxy) in front of the server.
A Dockerfile is provided for running keep-mcp as a containerized Streamable HTTP server listening on port 8000.
Build the container image:
docker build -t keep-mcp .
Run the container:
docker run -d \
-e GOOGLE_EMAIL="you@example.com" \
-e GOOGLE_MASTER_TOKEN="aas_et/..." \
-p 127.0.0.1:8000:8000 \
keep-mcp
[!WARNING] The container has no built-in authentication. Publish it only to localhost (
-p 127.0.0.1:8000:8000) or place it behind an authenticating reverse proxy if exposing it over a network.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by headroomlabs-ai
Compress tool outputs, logs, files, RAG chunks, and conversation history before they reach the LLM, keeping answers identical while saving up to 95% of tokens for JSON payloads.
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
{
"mcpServers": {
"keep-mcp-pipx": {
"command": "pipx",
"args": [
"run",
"keep-mcp"
],
"env": {
"GOOGLE_EMAIL": "<YOUR_GOOGLE_EMAIL>",
"GOOGLE_MASTER_TOKEN": "<YOUR_MASTER_TOKEN>",
"UNSAFE_MODE": "false"
}
}
}
}claude mcp add keep-mcp-pipx pipx run keep-mcp