# google-keep-mcp

An [MCP](https://modelcontextprotocol.io) 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`](https://github.com/kiwiz/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.

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/)

## Setup

```bash
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](https://gkeepapi.readthedocs.io/en/latest/#logging-in)),
then set `GOOGLE_KEEP_EMAIL` and `GOOGLE_KEEP_MASTER_TOKEN` — see
[.env.example](.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:

```bash
uv run google-keep-mcp
```

Register it with a client — for Claude Code:

```bash
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

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

## License

MIT — see [LICENSE](LICENSE).