Google Keep

by feuerdev

48 stars
759 downloads
Not rated
GitHub

About

Provides a bridge to Google Keep for searching, creating, updating, and deleting notes with safety features that restrict modifications to specifically labeled content.

Details

Author
feuerdev
Repository
feuerdev/keep-mcp
GitHub stars
48
Downloads
759
License
MIT License
Categories
Productivity, Community, Other, AI, Developer Tools, Search, Infrastructure, API, Security
Tags
#integration

Jump to

- Search notes with filters for labels, colors, pinned/archived/trashed state
- Create and update notes, checklist notes, and list items
- Pin, archive, trash, restore, or delete notes
- Set note color from twelve predefined values
- Add, remove, and list labels and collaborators
- List media blobs attached to a note
- Safety mode restricts destructive operations to server‑created notes

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Google Keep
    Command (node, npx, python, etc.) uv
    Arguments
    • Argument 1 --directory
    • Argument 2 /ABSOLUTE/PATH/TO/keep-mcp
    • Argument 3 run
    • Argument 4 --no-sync
    • Argument 5 --python
    • Argument 6 .venv/bin/python
    • Argument 7 -m
    • Argument 8 server
    Environment
    • UNSAFE_MODE false
    • GOOGLE_EMAIL Your Google Email
    • GOOGLE_MASTER_TOKEN Your Google Master Token - see README.md

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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

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.

get_note

Get a single note by ID.

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.

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.

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "google keep": {
            "env": {
                "UNSAFE_MODE": "false",
                "GOOGLE_EMAIL": "Your Google Email",
                "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
            },
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/keep-mcp",
                "run",
                "--no-sync",
                "--python",
                ".venv/bin/python",
                "-m",
                "server"
            ],
            "command": "uv"
        }
    }
}

Linux

{
    "env": {
        "UNSAFE_MODE": "false",
        "GOOGLE_EMAIL": "Your Google Email",
        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
    },
    "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/keep-mcp",
        "run",
        "--no-sync",
        "--python",
        ".venv/bin/python",
        "-m",
        "server"
    ],
    "command": "uv"
}

Macos

{
    "env": {
        "UNSAFE_MODE": "false",
        "GOOGLE_EMAIL": "Your Google Email",
        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
    },
    "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/keep-mcp",
        "run",
        "--no-sync",
        "--python",
        ".venv/bin/python",
        "-m",
        "server"
    ],
    "command": "uv"
}

Windows

{
    "env": {
        "UNSAFE_MODE": "false",
        "GOOGLE_EMAIL": "Your Google Email",
        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
    },
    "args": [
        "/c",
        "uv",
        "--directory",
        "/ABSOLUTE/PATH/TO/keep-mcp",
        "run",
        "--no-sync",
        "--python",
        ".venv/bin/python",
        "-m",
        "server"
    ],
    "command": "cmd"
}

keep-mcp

MCP server for Google Keep

keep-mcp

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

Or with uvx:

  "mcpServers": {
    "keep-mcp": {
      "command": "uvx",
      "args": [
        "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

Obtain a Google master token

keep-mcp uses gkeepapi, 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.

Use the browser-assisted token exchange documented by gpsoauth. Choose how you want to run the exchange:

Local Python: Follow gpsoauth's alternative flow.
 Docker: Follow gkeepapi's "Obtaining a Master Token" instructions. This runs the same exchange without requiring a local Python installation.

Both options require the browser oauth_token described in the gpsoauth documentation.

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.

Features

Query and read tools

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 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"
]
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "google keep": {
            "env": {
                "UNSAFE_MODE": "false",
                "GOOGLE_EMAIL": "Your Google Email",
                "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
            },
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/keep-mcp",
                "run",
                "--no-sync",
                "--python",
                ".venv/bin/python",
                "-m",
                "server"
            ],
            "command": "uv"
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other