# Google Keep MCP Server

A Model Context Protocol (MCP) server that connects Google Keep to Claude, giving it full note management capabilities.

Uses the unofficial [`gkeepapi`](https://github.com/kiwiz/gkeepapi) library — the only viable way to access Google Keep programmatically.

## Features

**20 tools** across 5 categories:

| Category | Tools |
|---|---|
| Search & Retrieval | `find`, `get_note`, `list_note_media` |
| Note CRUD | `create_note`, `create_list`, `update_note`, `set_note_color`, `delete_note`, `restore_note` |
| Note State | `pin_note`, `archive_note`, `trash_note` |
| Checklists | `add_list_item`, `update_list_item`, `delete_list_item` |
| Labels | `list_labels`, `create_label`, `delete_label`, `add_label_to_note`, `remove_label_from_note` |

## Setup

### 1. Install

```bash
make install
```

### 2. Get a Google Master Token

Google no longer allows programmatic login. You need to extract a token from a browser session:

1. Open Chrome and go to `https://accounts.google.com/EmbeddedSetup`
2. Sign in with your Google account and click "I agree"
   (the page may show a loading screen forever — that's OK)
3. Open DevTools (`Cmd+Option+I` on Mac, `F12` on Windows/Linux)
4. Go to **Application > Cookies > accounts.google.com**
5. Find the cookie named `oauth_token` and copy its value (starts with `oauth2_4/...`)
6. Run the helper script **immediately** (the token is single-use and short-lived):

```bash
uv run python scripts/get_token.py
```

The master token it returns **does not expire**. You only need to do this once.

### 3. Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-keep": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/Google Keep MCP", "run", "keep-mcp"],
      "env": {
        "GOOGLE_EMAIL": "you@gmail.com",
        "GOOGLE_MASTER_TOKEN": "aas_et/..."
      }
    }
  }
}
```

> Use the full path to `uv` (run `which uv` to find it). Claude Desktop doesn't inherit your shell PATH.

Restart Claude Desktop after saving.

## Safety

By default, write operations only work on notes that have a `keep-mcp` label. Notes created through the server get this label automatically.

This prevents Claude from accidentally modifying your existing notes.

To allow modifications to **all** notes, add to the env:

```json
"UNSAFE_MODE": "true"
```

Additional safety gates:
- `delete_note` (permanent delete) requires `UNSAFE_MODE=true`
- `delete_label` (globally destructive) requires `UNSAFE_MODE=true`
- `trash_note` is always available as a safe, reversible alternative

## Development

```bash
make install      # install dependencies
make start        # run server (stdio)
make start-sse    # run server (SSE for remote use)
make test         # run unit tests
make smoke        # run integration tests (needs credentials)
make lint         # check code style
make format       # auto-fix code style
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `GOOGLE_EMAIL` | Yes | Your Google account email |
| `GOOGLE_MASTER_TOKEN` | Yes | Master token from setup step 2 |
| `UNSAFE_MODE` | No | Set to `true` to allow modifying all notes |