Keep MCP

1# keep-mcp
2 
3MCP server for Google Keep
4 
5![keep-mcp](https://github.com/user-attachments/assets/f50c4ae6-4d35-4bb6-a494-51c67385f1b6)
6 
7## How to use
8 
91. Add the MCP server to your MCP servers:
10 
11```json
12  "mcpServers": {
13    "keep-mcp-pipx": {
14      "command": "pipx",
15      "args": [
16        "run",
17        "keep-mcp"
18      ],
19      "env": {
20        "GOOGLE_EMAIL": "Your Google Email",
21        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
22      }
23    }
24  }
25```
26 
272. Add your credentials:
28* `GOOGLE_EMAIL`: Your Google account email address
29* `GOOGLE_MASTER_TOKEN`: Your Google account master token
30 
31Check 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.
32 
33## Features
34 
35### Query and read tools
36* `find`: Search notes with optional filters for labels, colors, pinned, archived, and trashed
37* `get_note`: Get a single note by ID
38 
39### Creation and update tools
40* `create_note`: Create a new note with title and text (automatically adds keep-mcp label)
41* `create_list`: Create a checklist note
42* `update_note`: Update a note's title and text
43* `add_list_item`: Add an item to a checklist note
44* `update_list_item`: Update checklist item text and checked state
45* `delete_list_item`: Delete a checklist item
46 
47### Note state tools
48* `set_note_color`: Set a note color (valid values: DEFAULT, RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN, PURPLE, PINK, BROWN, GRAY)
49* `pin_note`: Pin or unpin a note
50* `archive_note`: Archive or unarchive a note
51* `trash_note`: Move a note to trash
52* `restore_note`: Restore a trashed/deleted note
53* `delete_note`: Mark a note for deletion
54 
55### Labels, collaborators, and media tools
56* `list_labels`: List labels
57* `create_label`: Create a label
58* `delete_label`: Delete a label
59* `add_label_to_note`: Add a label to a note
60* `remove_label_from_note`: Remove a label from a note
61* `list_note_collaborators`: List collaborator emails for a note
62* `add_note_collaborator`: Add a collaborator email to a note
63* `remove_note_collaborator`: Remove a collaborator email from a note
64* `list_note_media`: List media blobs for a note (with media links)
65 
66By 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.
67 
68```
69"env": {
70  ...
71  "UNSAFE_MODE": "true"
72}
73```
74 
75## Local development (uv + make)
76 
77If you prefer a JS-style workflow (`npm i`, `npm start`), use the included `Makefile`:
78 
79```bash
80make install   # like npm i
81make start     # like npm start
82make test
83make lint
84```
85 
86Run the real-account smoke test with credentials:
87 
88```bash
89GOOGLE_EMAIL="you@example.com" \
90GOOGLE_MASTER_TOKEN="..." \
91make smoke
92```
93 
94Equivalent direct `uv` commands (without `make`):
95 
96```bash
97UV_CACHE_DIR=/tmp/uv-cache uv venv --python 3.11 .venv
98UV_CACHE_DIR=/tmp/uv-cache uv pip install --python .venv/bin/python -e .
99UV_CACHE_DIR=/tmp/uv-cache uv run --no-sync --python .venv/bin/python -m server
100```
101 
102## Testing
103 
104### Unit tests (default)
105The project includes a lightweight unit test suite under `tests/`.
106 
107It validates:
108* note serialization shape for note and list objects (including labels, collaborators, media, and list items)
109* modification safety behavior (`keep-mcp` label requirement and `UNSAFE_MODE=true` override)
110* MCP tool behavior in `src/server/cli.py` using mocked Keep client objects (tool happy paths and key error paths)
111 
112Run locally:
113 
114```bash
115make test
116```
117 
118### Smoke test against a real Keep account
119For additional confidence, run a basic lifecycle smoke test against a dedicated test account:
120 
121```bash
122GOOGLE_EMAIL="you@example.com" \
123GOOGLE_MASTER_TOKEN="..." \
124make smoke
125```
126 
127What it does:
128* create note
129* update note
130* pin/unpin
131* archive/unarchive
132* trash/restore
133* delete
134 
135This script is intended for manual verification and is not run in CI.
136 
137### CI checks
138GitHub Actions runs on every pull request and executes:
139* lint (`ruff check .`)
140* unit tests with coverage (`pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70`)
141* bytecode sanity (`python -m compileall src`)
142 
143## Publishing
144 
145### Automatic publish on merge to `main` (GitHub Actions)
146 
147This repo includes a release workflow at `.github/workflows/release.yml` that runs on every push to `main` (including merged PRs).
148 
149It will:
150* inspect commits since the last release tag (`vX.Y.Z`)
151* compute the next semantic version from Conventional Commit types
152* skip publishing when there are no releasable commit types
153* run lint and unit tests
154* build `dist/*`
155* publish to PyPI
156* create a GitHub release/tag `v<computed-version>` with generated notes
157 
158Version bump rules:
159* major: commit subject with `!` (example: `feat!:` or `fix(api)!:`) or commit body containing `BREAKING CHANGE`
160* minor: `feat:`
161* patch: `fix:`, `perf:`, `revert:`
162* no release: `docs:`, `chore:`, `ci:`, `test:`, `refactor:` (unless the commit is marked as breaking)
163 
164Required repository secret:
165* `PYPI_API_TOKEN`: a PyPI API token (recommended scope: this project only)
166 
167### Manual publish
168 
169To publish manually to PyPI:
170 
1711. Update the version in `pyproject.toml`
1722. Build the package:
173   ```bash
174   pipx run build
175   ```
1763. Upload to PyPI:
177   ```bash
178   pipx run twine upload --repository pypi dist/*
179   ```
180 
181## Run locally with MCP clients
182 
183This is useful when you want a client to run this server from your local checkout instead of PyPI.
184 
1851. Create a local virtualenv and install in editable mode:
186 
187```bash
188cd /ABSOLUTE/PATH/TO/keep-mcp
189make install
190```
191 
1922. Add the server to your MCP client config.
193 
194### `config.toml` clients (Codex, Goose, etc.)
195 
196```toml
197[mcp_servers.keep_mcp]
198command = "make"
199args = ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"]
200 
201[mcp_servers.keep_mcp.env]
202GOOGLE_EMAIL = "you@example.com"
203GOOGLE_MASTER_TOKEN = "your-master-token"
204UNSAFE_MODE = "false"
205```
206 
207### JSON `mcpServers` clients (Claude Desktop, Cursor, Cline, etc.)
208 
209```json
210{
211  "mcpServers": {
212    "keep-mcp-local": {
213      "command": "make",
214      "args": ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"],
215      "env": {
216        "GOOGLE_EMAIL": "you@example.com",
217        "GOOGLE_MASTER_TOKEN": "your-master-token",
218        "UNSAFE_MODE": "false"
219      }
220    }
221  }
222}
223```
224 
225Alternative (without `make`):
226 
227```toml
228[mcp_servers.keep_mcp]
229command = "uv"
230args = [
231  "--directory", "/ABSOLUTE/PATH/TO/keep-mcp",
232  "run", "--no-sync", "--python", ".venv/bin/python",
233  "-m", "server"
234]
235```
236 
237Notes:
238* Run `make install` once before starting from an MCP client.
239* Only the repo root path is required (no absolute `/.venv/bin/python` path).
240* Ensure `make` and `uv` are in your `PATH`.
241* Restart your MCP client after updating config files.
242* `UNSAFE_MODE` is optional; keep it `"false"` unless you explicitly want to modify non-`keep-mcp` notes.
243 
244## Troubleshooting
245 
246* If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"
247