keep-mcp

MCP server for Google Keep

How to use

1. 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"
      }
    }
  }

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)

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"
}

Local development (uv + make)

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

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:

make test

Smoke test against a real Keep account

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:

• 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` 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:

cd /ABSOLUTE/PATH/TO/keep-mcp
make install

2. Add the server to your MCP client config.

`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"

JSON `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:

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