# keep-mcp
MCP server for Google Keep
## How to use
1. Add the MCP server to your MCP servers:
```json
"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.
## 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`:
```bash
make install # like npm i
make start # like npm start
make test
make lint
```
Run the real-account smoke test with credentials:
```bash
GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smoke
```
Equivalent direct `uv` commands (without `make`):
```bash
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:
```bash
make test
```
### Smoke test against a real Keep account
For additional confidence, run a basic lifecycle smoke test against a dedicated test account:
```bash
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:
```bash
pipx run build
```
3. Upload to PyPI:
```bash
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:
```bash
cd /ABSOLUTE/PATH/TO/keep-mcp
make install
```
2. Add the server to your MCP client config.
### `config.toml` clients (Codex, Goose, etc.)
```toml
[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.)
```json
{
"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`):
```toml
[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)"
