keep-mcp

MCP server for Google Keep

How to use

1. Add the MCP server to your MCP servers:

2. Add your credentials:

• GOOGLE_EMAIL: Your Google account email address

• GOOGLE_MASTER_TOKEN: Your Google account master token

Check https://gkeepapi.readthedocs.io/en/latest/#obtaining-a-master-token and https://github.com/simon-weber/gpsoauth?tab=readme-ov-file#alternative-flow for more information.

Related MCP server: Google Drive MCP Server

Features

Query and read tools

• find: Search notes with optional filters for labels, colors, pinned, archived, and trashed

• 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)

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)

The 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-mcp label requirement and UNSAFE_MODE=true override)

• MCP tool behavior in src/server/cli.py using mocked Keep client objects (tool happy paths and key error paths)

Run locally:

Smoke test against a real Keep account

For additional confidence, run a basic lifecycle smoke test against a dedicated test account:

What 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.

CI checks

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)

Publishing

Automatic publish on merge to 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:

• 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!: or fix(api)!:) or commit body containing BREAKING 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)

Manual publish

To publish manually to PyPI:

1. Update the version in pyproject.toml

2. Build the package:

   pipx run build

3. Upload to PyPI:

   pipx run twine upload --repository pypi dist/*

Run locally with MCP clients

This is useful when you want a client to run this server from your local checkout instead of PyPI.

1. Create a local virtualenv and install in editable mode:

2. Add the server to your MCP client config.

config.toml clients (Codex, Goose, etc.)

JSON mcpServers clients (Claude Desktop, Cursor, Cline, etc.)

Alternative (without make):

Notes:

• Run make install once before starting from an MCP client.

• Only the repo root path is required (no absolute /.venv/bin/python path).

• Ensure make and uv are in your PATH.

• Restart your MCP client after updating config files.

• UNSAFE_MODE is optional; keep it "false" unless you explicitly want to modify non-keep-mcp notes.

Troubleshooting

• If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"