feuerdev/keep-mcp

MCP server for Google Keep
See CONTRIBUTING.md for contribution guidelines and required visual evidence.
How to use
1. Add the MCP server to your MCP servers:
Or with uvx:
2. Add your credentials:
* GOOGLE_EMAIL: Your Google account email address
* GOOGLE_MASTER_TOKEN: Your Google account master token
Obtain a Google 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.
Use the browser-assisted token exchange documented by gpsoauth. Choose how you want to run the exchange:
* **Local Python:** Follow gpsoauth's alternative flow.
* **Docker:** Follow gkeepapi's "Obtaining a Master Token" instructions. This runs the same exchange without requiring a local Python installation.
Both options require the browser oauth_token described in the gpsoauth documentation.
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.
Features
Query and read tools
* 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
* get_note: Get a single note by ID
Creation and update tools
* create_note: Create a new note with title and text (automatically adds keep-mcp label)
* create_list: Create a checklist note
* update_note: Update a note's title and text
* add_list_item: Add an item to a checklist note
* update_list_item: Update checklist item text and checked state
* delete_list_item: Delete a checklist item
Note state tools
* 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 note
* archive_note: Archive or unarchive a note
* trash_note: Move a note to trash
* restore_note: Restore a trashed/deleted note
* delete_note: Mark a note for deletion
Labels, collaborators, and media tools
* list_labels: List labels
* create_label: Create a label
* delete_label: Delete a label
* add_label_to_note: Add a label to a note
* remove_label_from_note: Remove a label from a note
* list_note_collaborators: List collaborator emails for a note
* add_note_collaborator: Add a collaborator email to a note
* remove_note_collaborator: Remove a collaborator email from a note
* list_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)
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.
Local development (uv + make)
If you prefer a JS-style workflow (npm i, npm start), use the included Makefile:
Run the real-account smoke test with credentials:
Equivalent direct uv commands (without make):
Testing
Unit tests (default)