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:

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

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