MCP server for Google Keep
See CONTRIBUTING.md for contribution guidelines and required visual evidence.
- Add the MCP server to your MCP servers:
"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"
}
}
}- Add your credentials:
GOOGLE_EMAIL: Your Google account email addressGOOGLE_MASTER_TOKEN: Your Google account master token
keep-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_tokencookie:- Chrome or Edge: Press F12, open the Application tab, then Cookies →
https://accounts.google.com. - Firefox: Press F12, open the Storage tab, then Cookies →
https://accounts.google.com.
Find the row named
oauth_tokenand copy its value. It starts withoauth2_4/. - Chrome or Edge: Press F12, open the Application tab, then Cookies →
-
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-slimpart. -
The command prints your master token. It starts with
aas_et/. Use it asGOOGLE_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.- gkeepapi's "Obtaining a Master Token" instructions describe the same 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 ID
create_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 item
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 deletion
list_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 server
By 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 lintRun the real-account smoke test with credentials:
GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smokeEquivalent 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 serverThe project includes a lightweight unit test suite under tests/.
It validates:
- note serialization shape for note and list objects (including labels, collaborators, media, and list items)
- modification safety behavior (
keep-mcplabel requirement andUNSAFE_MODE=trueoverride) - MCP tool behavior in
src/server/cli.pyusing mocked Keep client objects (tool happy paths and key error paths)
Run locally:
make testFor additional confidence, run a basic lifecycle smoke test against a dedicated test account:
GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smokeWhat it does:
- create note
- update note
- pin/unpin
- archive/unarchive
- trash/restore
- delete
This script is intended for manual verification and is not run in CI.
GitHub Actions runs on every pull request and executes:
- lint (
ruff check .) - unit tests with coverage (
pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70) - bytecode sanity (
python -m compileall src)
This repo includes a release workflow at .github/workflows/release.yml that runs on every push to main (including merged PRs).
It will:
- inspect commits since the last release tag (
vX.Y.Z) - compute the next semantic version from Conventional Commit types
- skip publishing when there are no releasable commit types
- run lint and unit tests
- build
dist/* - publish to PyPI
- create a GitHub release/tag
v<computed-version>with generated notes
Version bump rules:
- major: commit subject with
!(example:feat!:orfix(api)!:) or commit body containingBREAKING CHANGE - minor:
feat: - patch:
fix:,perf:,revert: - no release:
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:
- Update the version in
pyproject.toml - Build the package:
pipx run build
- Upload to PyPI:
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.
- Create a local virtualenv and install in editable mode:
cd /ABSOLUTE/PATH/TO/keep-mcp
make install- Add the server to your MCP client config.
[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": {
"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:
- Run
make installonce before starting from an MCP client. - Only the repo root path is required (no absolute
/.venv/bin/pythonpath). - Ensure
makeanduvare in yourPATH. - Restart your MCP client after updating config files.
UNSAFE_MODEis optional; keep it"false"unless you explicitly want to modify non-keep-mcpnotes.
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 8000Note
keep-mcp binds to 127.0.0.1 by 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.
- If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"