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

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.

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