Skip to content
Back to search

keep-mcp

MCP server for Google Keep

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/feuerdev/keep-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/feuerdev/keep-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/feuerdev--keep-mcp/badge.svg)](/listings/feuerdev--keep-mcp)

HTML

<a href="/listings/feuerdev--keep-mcp"><img src="/api/listings/feuerdev--keep-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 383 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # keep-mcp
  2. MCP server for Google Keep
  3. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and required visual evidence.
  4. ![keep-mcp](https://github.com/user-attachments/assets/f50c4ae6-4d35-4bb6-a494-51c67385f1b6)
  5. ## How to use
  6. 1. Add the MCP server to your MCP servers:
  7. ```json
  8. "mcpServers": {
  9. "keep-mcp-pipx": {
  10. "command": "pipx",
  11. "args": [
  12. "run",
  13. "keep-mcp"
  14. ],
  15. "env": {
  16. "GOOGLE_EMAIL": "Your Google Email",
  17. "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
  18. }
  19. }
  20. }
  21. ```
  22. Or with `uvx`:
  23. ```json
  24. "mcpServers": {
  25. "keep-mcp": {
  26. "command": "uvx",
  27. "args": [
  28. "keep-mcp"
  29. ],
  30. "env": {
  31. "GOOGLE_EMAIL": "Your Google Email",
  32. "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
  33. }
  34. }
  35. }
  36. ```
  37. 2. Add your credentials:
  38. * `GOOGLE_EMAIL`: Your Google account email address
  39. * `GOOGLE_MASTER_TOKEN`: Your Google account master token
  40. ### Obtain a Google master token
  41. `keep-mcp` uses [gkeepapi](https://gkeepapi.readthedocs.io/), 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.
  42. You need [Docker](https://docs.docker.com/get-started/get-docker/) and a desktop browser.
  43. 1. Open https://accounts.google.com/EmbeddedSetup and sign in with the Google account you use for Keep.
  44. 2. Click **I agree**. The page may keep loading forever. Leave it open and continue.
  45. 3. Copy the `oauth_token` cookie:
  46. * **Chrome or Edge:** Press F12, open the **Application** tab, then **Cookies** → `https://accounts.google.com`.
  47. * **Firefox:** Press F12, open the **Storage** tab, then **Cookies** → `https://accounts.google.com`.
  48. Find the row named `oauth_token` and copy its value. It starts with `oauth2_4/`.
  49. 4. Right away, run this in a terminal and paste your email and the cookie value when asked:
  50. ```bash
  51. docker run --rm -it ghcr.io/astral-sh/uv:python3.13-bookworm-slim uv run --no-project --with gpsoauth python -c "import gpsoauth; r = gpsoauth.exchange_token(input('Email: '), input('oauth_token: '), '0123456789abcdef'); print(r.get('Token', r))"
  52. ```
  53. Without Docker, install [uv](https://docs.astral.sh/uv/getting-started/installation/) and run the same command without the `docker run --rm -it ghcr.io/astral-sh/uv:python3.13-bookworm-slim` part.
  54. 5. The command prints your master token. It starts with `aas_et/`. Use it as `GOOGLE_MASTER_TOKEN`.
  55. If it prints an error such as `BadAuthentication` instead, the cookie has expired. Repeat steps 1 to 4 to get a fresh one.
  56. #### More details
  57. * [`gpsoauth`'s alternative flow](https://github.com/simon-weber/gpsoauth#alternative-flow) describes the token exchange.
  58. * [gkeepapi's "Obtaining a Master Token" instructions](https://gkeepapi.readthedocs.io/en/latest/#obtaining-a-master-token) describe the same exchange.
  59. 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.
  60. ## Features
  61. ### Query and read tools
  62. * `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 (default 50)
  63. * `get_note`: Get a single note by ID
  64. ### Creation and update tools
  65. * `create_note`: Create a new note with title and text (automatically adds keep-mcp label)
  66. * `create_list`: Create a checklist note
  67. * `update_note`: Update a note's title and text
  68. * `add_list_item`: Add an item to a checklist note
  69. * `update_list_item`: Update checklist item text and checked state
  70. * `delete_list_item`: Delete a checklist item
  71. * `move_list_item`: Move an item to a zero-based final position
  72. * `reorder_list_items`: Bulk reorder a checklist using all its item IDs
  73. * `replace_list_items`: Replace the entire checklist, creating new item IDs
  74. #### Checklist ordering and replacement
  75. Get the current item IDs and order with `get_note`. `move_list_item` takes
  76. `note_id`, `item_id`, and `position`: `0` means first, and the last valid position
  77. is the item count minus one. The position is the item's final index after moving.
  78. For bulk ordering, call `reorder_list_items` with `note_id` and `item_ids` in the
  79. desired first-to-last order. Supply **every current item ID exactly once**, including
  80. checked items. Missing, duplicate, unknown, foreign, or deleted IDs are rejected
  81. before mutation. Ordering preserves item IDs, text and checked states. Positions
  82. refer to the combined order returned by `get_note`; Keep may display checked items
  83. in a separate section according to its settings.
  84. Example tool arguments (substitute IDs returned by `get_note`):
  85. ```json
  86. {"note_id":"NOTE_ID","item_id":"THIRD_ITEM_ID","position":0}
  87. ```
  88. ```json
  89. {"note_id":"NOTE_ID","item_ids":["THIRD_ITEM_ID","FIRST_ITEM_ID","SECOND_ITEM_ID"]}
  90. ```
  91. `replace_list_items` takes `note_id` and an `items` array. Each item requires
  92. `text`; `checked` is optional and defaults to `false`. Only these two item fields
  93. are accepted. The full payload is validated before any item is changed. All old
  94. items are marked for deletion and new items are created in input order with new
  95. IDs. The note itself, title, labels, collaborators and other note metadata remain.
  96. Passing `items: []` clears the checklist; an empty bulk order is valid only for an
  97. already empty checklist.
  98. ```json
  99. {"note_id":"NOTE_ID","items":[{"text":"Milk","checked":false},{"text":"Bread","checked":true}]}
  100. ```
  101. All three tools currently require flat checklists: an existing checklist with
  102. indented items is rejected without changes, so hierarchy cannot be silently lost.
  103. They are annotated as destructive because ordering overwrites the existing order
  104. and replacement deletes the old items.
  105. They use the same keep-mcp label / `UNSAFE_MODE` restriction as other modification
  106. tools. They refresh through the shared client, then sync once after mutation.
  107. Moving an item to its current position or supplying the current bulk order leaves
  108. the items untouched and skips the post-mutation sync.
  109. This is not a server-side atomic transaction: a network failure can leave the
  110. remote outcome uncertain. Read the note again before retrying, particularly after
  111. replacement. Concurrent external edits can also affect the final order.
  112. ### Note state tools
  113. * `set_note_color`: Set a note color (valid values: DEFAULT, RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN, PURPLE, PINK, BROWN, GRAY)
  114. * `pin_note`: Pin or unpin a note
  115. * `archive_note`: Archive or unarchive a note
  116. * `trash_note`: Move a note to trash
  117. * `restore_note`: Restore a trashed/deleted note
  118. * `delete_note`: Mark a note for deletion
  119. ### Labels, collaborators, and media tools
  120. * `list_labels`: List labels
  121. * `create_label`: Create a label
  122. * `delete_label`: Delete a label
  123. * `add_label_to_note`: Add a label to a note
  124. * `remove_label_from_note`: Remove a label from a note
  125. * `list_note_collaborators`: List collaborator emails for a note
  126. * `add_note_collaborator`: Add a collaborator email to a note
  127. * `remove_note_collaborator`: Remove a collaborator email from a note
  128. * `list_note_media`: List media blobs for a note (with media links)
  129. * `download_media`: Download a note's media (images, drawings, audio) to a local directory through the authenticated session (the raw media links answer 403 to plain HTTP clients). Not available over Streamable HTTP, where the files would land on the server
  130. 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.
  131. ```
  132. "env": {
  133. ...
  134. "UNSAFE_MODE": "true"
  135. }
  136. ```
  137. ## Local development (uv + make)
  138. If you prefer a JS-style workflow (`npm i`, `npm start`), use the included `Makefile`:
  139. ```bash
  140. make install # like npm i
  141. make start # like npm start
  142. make test
  143. make lint
  144. ```
  145. Run the real-account smoke test with credentials:
  146. ```bash
  147. GOOGLE_EMAIL="you@example.com" \
  148. GOOGLE_MASTER_TOKEN="..." \
  149. make smoke
  150. ```
  151. Equivalent direct `uv` commands (without `make`):
  152. ```bash
  153. UV_CACHE_DIR=/tmp/uv-cache uv venv --python 3.11 .venv
  154. UV_CACHE_DIR=/tmp/uv-cache uv pip install --python .venv/bin/python -e .
  155. UV_CACHE_DIR=/tmp/uv-cache uv run --no-sync --python .venv/bin/python -m server
  156. ```
  157. ## Testing
  158. ### Unit tests (default)
  159. The project includes a lightweight unit test suite under `tests/`.
  160. It validates:
  161. * note serialization shape for note and list objects (including labels, collaborators, media, and list items)
  162. * modification safety behavior (`keep-mcp` label requirement and `UNSAFE_MODE=true` override)
  163. * MCP tool behavior in `src/server/cli.py` using mocked Keep client objects (tool happy paths and key error paths)
  164. Run locally:
  165. ```bash
  166. make test
  167. ```
  168. ### Smoke test against a real Keep account
  169. For additional confidence, run a basic lifecycle smoke test against a dedicated test account:
  170. ```bash
  171. GOOGLE_EMAIL="you@example.com" \
  172. GOOGLE_MASTER_TOKEN="..." \
  173. make smoke
  174. ```
  175. What it does:
  176. * create note
  177. * update note
  178. * pin/unpin
  179. * archive/unarchive
  180. * trash/restore
  181. * delete
  182. This script is intended for manual verification and is not run in CI.
  183. ### CI checks
  184. GitHub Actions runs on every pull request and executes:
  185. * lint (`ruff check .`)
  186. * unit tests with coverage (`pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70`)
  187. * bytecode sanity (`python -m compileall src`)
  188. ## Publishing
  189. ### Automatic publish on merge to `main` (GitHub Actions)
  190. This repo includes a release workflow at `.github/workflows/release.yml` that runs on every push to `main` (including merged PRs).
  191. It will:
  192. * inspect commits since the last release tag (`vX.Y.Z`)
  193. * compute the next semantic version from Conventional Commit types
  194. * skip publishing when there are no releasable commit types
  195. * run lint and unit tests
  196. * build `dist/*`
  197. * publish to PyPI
  198. * create a GitHub release/tag `v<computed-version>` with generated notes
  199. Version bump rules:
  200. * major: commit subject with `!` (example: `feat!:` or `fix(api)!:`) or commit body containing `BREAKING CHANGE`
  201. * minor: `feat:`
  202. * patch: `fix:`, `perf:`, `revert:`
  203. * no release: `docs:`, `chore:`, `ci:`, `test:`, `refactor:` (unless the commit is marked as breaking)
  204. Required repository secret:
  205. * `PYPI_API_TOKEN`: a PyPI API token (recommended scope: this project only)
  206. ### Manual publish
  207. To publish manually to PyPI:
  208. 1. Update the version in `pyproject.toml`
  209. 2. Build the package:
  210. ```bash
  211. pipx run build
  212. ```
  213. 3. Upload to PyPI:
  214. ```bash
  215. pipx run twine upload --repository pypi dist/*
  216. ```
  217. ## Run locally with MCP clients
  218. This is useful when you want a client to run this server from your local checkout instead of PyPI.
  219. 1. Create a local virtualenv and install in editable mode:
  220. ```bash
  221. cd /ABSOLUTE/PATH/TO/keep-mcp
  222. make install
  223. ```
  224. 2. Add the server to your MCP client config.
  225. ### `config.toml` clients (Codex, Goose, etc.)
  226. ```toml
  227. [mcp_servers.keep_mcp]
  228. command = "make"
  229. args = ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"]
  230. [mcp_servers.keep_mcp.env]
  231. GOOGLE_EMAIL = "you@example.com"
  232. GOOGLE_MASTER_TOKEN = "your-master-token"
  233. UNSAFE_MODE = "false"
  234. ```
  235. ### JSON `mcpServers` clients (Claude Desktop, Cursor, Cline, etc.)
  236. ```json
  237. {
  238. "mcpServers": {
  239. "keep-mcp-local": {
  240. "command": "make",
  241. "args": ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"],
  242. "env": {
  243. "GOOGLE_EMAIL": "you@example.com",
  244. "GOOGLE_MASTER_TOKEN": "your-master-token",
  245. "UNSAFE_MODE": "false"
  246. }
  247. }
  248. }
  249. }
  250. ```
  251. Alternative (without `make`):
  252. ```toml
  253. [mcp_servers.keep_mcp]
  254. command = "uv"
  255. args = [
  256. "--directory", "/ABSOLUTE/PATH/TO/keep-mcp",
  257. "run", "--no-sync", "--python", ".venv/bin/python",
  258. "-m", "server"
  259. ]
  260. ```
  261. Notes:
  262. * Run `make install` once before starting from an MCP client.
  263. * Only the repo root path is required (no absolute `/.venv/bin/python` path).
  264. * Ensure `make` and `uv` are in your `PATH`.
  265. * Restart your MCP client after updating config files.
  266. * `UNSAFE_MODE` is optional; keep it `"false"` unless you explicitly want to modify non-`keep-mcp` notes.
  267. ## Running over Streamable HTTP
  268. `keep-mcp` supports the MCP Streamable HTTP transport (`/mcp` endpoint) in addition to the default `stdio` transport:
  269. ```bash
  270. # Start Streamable HTTP server on localhost (default: 127.0.0.1:8000)
  271. keep-mcp --transport streamable-http
  272. # Customize host or port
  273. keep-mcp --transport streamable-http --host 127.0.0.1 --port 8000
  274. ```
  275. > [!NOTE]
  276. > `keep-mcp` binds to `127.0.0.1` by default with DNS rebinding protection enabled. To expose the server to remote or web clients (such as Gemini web), place an authenticating proxy (such as [mcp-auth-proxy](https://github.com/sigbit/mcp-auth-proxy)) in front of the server.
  277. ## Running in Docker
  278. A `Dockerfile` is provided for running `keep-mcp` as a containerized Streamable HTTP server listening on port 8000.
  279. 1. Build the container image:
  280. ```bash
  281. docker build -t keep-mcp .
  282. ```
  283. 2. Run the container:
  284. ```bash
  285. docker run -d \
  286. -e GOOGLE_EMAIL="you@example.com" \
  287. -e GOOGLE_MASTER_TOKEN="aas_et/..." \
  288. -p 127.0.0.1:8000:8000 \
  289. keep-mcp
  290. ```
  291. > [!WARNING]
  292. > The container has no built-in authentication. Publish it only to localhost (`-p 127.0.0.1:8000:8000`) or place it behind an authenticating reverse proxy if exposing it over a network.
  293. ## Troubleshooting
  294. * If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.