Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/feuerdev/keep-mcp

MCP server for Google Keep
https://github.com/feuerdev/keep-mcp

Last synced: 22 days ago
JSON representation

MCP server for Google Keep

Awesome Lists containing this project

README 

          
# keep-mcp



MCP server for Google Keep



![keep-mcp](https://github.com/user-attachments/assets/f50c4ae6-4d35-4bb6-a494-51c67385f1b6)



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