Skip to main content
Glama
orssdev

google-keep-mcp

by orssdev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

google-keep-mcp

An MCP server that exposes Google Keep notes as tools, so an MCP client (Claude Code, Claude Desktop, etc.) can work with them.

Google Keep has no official public API. This project talks to Keep through gkeepapi, an unofficial client — expect it to break whenever Google changes the private endpoints.

Tools

Tool

Does

list_notes

Search the account's notes. Filters: query, labels, pinned, archived, trashed, limit. Returns id, title, text, labels, color, timestamps and the Keep URL for each match.

delete_note

Move a note to the trash by id, or delete it outright with permanent: true.

Both tools sync with Google on every call, so results reflect the account's current state and deletions are pushed immediately.

Related MCP server: NotesKeep MCP Server

Requirements

  • Python 3.13+

  • uv

Setup

uv sync
cp .env.example .env   # then fill in your credentials

Credentials

gkeepapi authenticates with a Google master token, not your password. Obtain one once (see the gkeepapi docs), then set GOOGLE_KEEP_EMAIL and GOOGLE_KEEP_MASTER_TOKEN — see .env.example.

A master token grants full access to the account. Treat it like a password: keep it out of version control and out of shell history.

Running

The server speaks MCP over stdio:

uv run google-keep-mcp

Register it with a client — for Claude Code:

claude mcp add google-keep -- uv run --directory /path/to/google-keep-mcp google-keep-mcp

Credentials are read from the process environment, falling back to a .env file in the working directory. To pass them through the client config instead, add --env GOOGLE_KEEP_EMAIL=... --env GOOGLE_KEEP_MASTER_TOKEN=... to the command above. Sign-in is deferred until the first tool call, so a misconfigured server still starts and reports the problem in the tool result.

Development

uv run ruff check .      # lint
uv run ruff format .     # format
uv run pytest            # tests

License

MIT — see LICENSE.

Available Tools

2 tools
delete_noteDelete noteA
DestructiveIdempotent

Move a Google Keep note to the trash, or delete it permanently.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYesNote id, as returned by list_notes.
permanentNoDelete the note outright instead of moving it to the trash. Permanent deletion cannot be undone.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
titleYes
permanentYesTrue if the note was deleted outright, False if it was moved to the trash.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, so the description is not required to repeat that. It adds valuable context by distinguishing between the reversible trash action and the irreversible permanent deletion, explicitly warning that permanent deletion cannot be undone. This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that captures both behaviors with no extraneous words. It is optimally concise and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a simple interface with two well-documented parameters and an output schema, so the description does not need to explain return values. The description, combined with annotations and schema, gives the agent everything needed to call the tool correctly. It could optionally mention that the note must exist or that trash is reversible, but the schema covers the id, and the irreversibility warning is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters have clear descriptions. The tool description restates the two modes but adds little beyond the schema's own explanation of the permanent parameter. The description does not introduce any new semantic details about note_id or permanent beyond what the schema already provides, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Move a Google Keep note to the trash, or delete it permanently.' It clearly distinguishes the two deletion modes and is unambiguous about what the tool does. The sibling list_notes is obviously for listing, so there is no confusion about purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this tool is for deleting notes, and the sibling list_notes is for retrieval, so the alternative is obvious. The schema reinforces the workflow by noting note_id comes from list_notes. However, there is no explicit 'when not to use' or conditional guidance beyond the two modes, which are explained in the parameter descriptions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_notesList notesA
Read-only

Search the Google Keep account and return the matching notes.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum notes to return.
queryNoText to match against note titles and bodies. Omit to match all.
labelsNoLabel names a note must all carry, e.g. ['todo'].
pinnedNoFilter by pinned state.
trashedNoList trashed notes instead of live ones.
archivedNoFilter by archived state.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the account-wide search scope but otherwise mostly restates the retrieval behavior. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no filler. The action and resource are front-loaded, making it immediately scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema, full parameter descriptions, and annotations, the definition is complete enough for an agent to call the tool correctly. It could have explicitly mentioned default live-note behavior, but the schema already documents the trashed parameter default.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all six optional parameters, so the schema carries the semantic weight. The description adds no parameter-level detail, which is acceptable given the strong schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Search') and resource ('Google Keep notes'), and specifies the scope ('Google Keep account'). It is easy to distinguish from the sibling delete_note since this tool is retrieval-focused.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context is clear: use this tool when you need to find or list notes. It does not explicitly mention delete_note or state when not to use it, but the sibling's destructive purpose makes the distinction obvious. An explicit alternative note would have made this a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observeddelete_note
    • First observedlist_notes
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 2 tools

Disambiguation5/5

list_notes and delete_note target completely distinct actions with no overlap. An agent can easily choose the right tool based on the operation needed.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (list_notes, delete_note). The naming is predictable and uniform.

Tool Count3/5

With only 2 tools, the server feels thin for a Google Keep integration. The count is borderline but not absurdly small.

Completeness2/5

The surface lacks essential operations like creating, updating, or fetching a single note by ID. Only list and delete are supported, leaving significant workflow gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Keep MCP

    feuerdev
    A
    license
    B
    quality
    A
    maintenance
    Enables interaction with Google Keep notes through an MCP server, allowing users to search, create, update, and delete notes via natural language commands.
    23
    104
    MIT

  • NotesKeep MCP Server

    mariomosca
    A
    license
    C
    quality
    D
    maintenance
    Enables users to manage their notes on NotesKeep directly through Claude Code or other MCP clients. It supports creating, updating, and organizing both text and checklist notes using natural language commands.
    14
    10 npm
    1
    MIT