MCP Google Keep

An MCP (Model Context Protocol) server that enables AI assistants like Claude to access and manage Google Keep notes with zero-config OAuth authentication.

Features

Note Management: Create, retrieve, list, and delete notes
Checklist Support: Create notes with checkable list items
Attachment Access: List and download note attachments
Sharing: Share notes with users, groups, and families
Browser-Based Auth: OAuth 2.1 with PKCE - just sign in with your Google account

Prerequisites

Bun runtime
A Google account with access to Google Keep
Google Cloud OAuth 2.0 credentials (see setup below)

Installation

1. Create Google Cloud OAuth Credentials

Go to Google Cloud Console
Create a new project (or select an existing one)
Enable the Google Keep API:
- Go to APIs & Services → Library
- Search for and enable the Google Keep API
Configure the OAuth consent screen:
- Go to APIs & Services → OAuth consent screen
- Choose "External" user type
- Fill in the required fields (app name, support email)
- Add scopes: keep and drive.file
- Add your email as a test user (required while in testing mode)
Create OAuth 2.0 credentials:
- Go to APIs & Services → Credentials
- Click Create Credentials → OAuth client ID
- Choose Desktop app as the application type
- Save the Client ID and Client Secret

2. Clone and Install

git clone https://github.com/shanewwarren/mcp-google-keep.git
cd mcp-google-keep
bun install

3. Add to Claude Code

claude mcp add google-keep /path/to/mcp-google-keep/bin/mcp-google-keep \
  -e MCP_GKEEP_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  -e MCP_GKEEP_CLIENT_SECRET=your-client-secret

Replace /path/to/mcp-google-keep with where you cloned the repo, and add your OAuth credentials.

Then run /mcp in Claude Code to connect to the server.

For full MCP documentation, see Claude Code MCP docs.

Authentication

This server uses browser-based OAuth 2.1 with PKCE for authentication.

How It Works

First Tool Use: When you first invoke any tool (e.g., create_text_note), the server automatically opens your browser to Google's consent screen
Grant Permission: Sign in with your Google account and authorize the application
Automatic Token Storage: Tokens are securely stored locally at ~/.mcp-google-keep/tokens.json
Automatic Refresh: Access tokens are automatically refreshed before expiration

Multiple Users

The OAuth Client ID/Secret identify the application, not the user. Multiple people can use the same credentials to authenticate with their own Google accounts and access their own notes.

Note: While your app is in "testing" mode, only users added as test users in Google Cloud Console can authenticate. To allow anyone, publish the app (users will see an "unverified app" warning) or go through Google's verification process.

Re-authentication

If you need to re-authenticate (e.g., to switch accounts), delete the token file:

rm ~/.mcp-google-keep/tokens.json

The next tool invocation will trigger a new authentication flow.

OAuth Scopes

The server requests the following permissions:

| Scope | Purpose | |-------|---------| | keep | Access and manage Google Keep notes | | drive.file | Access files created by this application only |

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------|-------------| | MCP_GKEEP_CLIENT_ID | Yes | - | Google OAuth Client ID | | MCP_GKEEP_CLIENT_SECRET | Yes | - | Google OAuth Client Secret | | MCP_GKEEP_TOKEN_PATH | No | ~/.mcp-google-keep/tokens.json | Path to token storage file | | MCP_GKEEP_CALLBACK_PORT | No | 8085 | Port for OAuth callback server |

Available Tools

Note Management

| Tool | Description | |------|-------------| | create_text_note | Create a new text-based note | | create_list_note | Create a new checklist note with items | | get_note | Get details about a specific note | | list_notes | List all notes in your Google Keep | | delete_note | Delete a note |

Attachments

| Tool | Description | |------|-------------| | list_attachments | List all attachments on a note | | download_attachment | Download attachment content |

Sharing & Permissions

| Tool | Description | |------|-------------| | share_note | Share a note with users, groups, or families | | unshare_note | Remove sharing permissions from a note | | list_permissions | List all permissions on a note |

Example Usage

Here's a typical workflow for managing notes:

1. create_text_note → title: "Meeting Notes", content: "Discussed Q1 goals..."
2. create_list_note → title: "Shopping List", items: ["Milk", "Eggs", "Bread"]
3. list_notes → see all your notes
4. share_note → share with colleague@example.com
5. get_note → retrieve full note details

Google Keep API Limitations

The Google Keep API has some constraints to be aware of:

No Update Method: Notes cannot be modified after creation
No Labels: Label management is not exposed in the REST API
No Archive: Archive status is not accessible via the API
Single-Level Nesting: List items support only one level of child items
Attachment Download Only: Cannot upload attachments via the API

Development

# Install dependencies
bun install

# Run in development mode (with hot reload)
bun run dev

# Run tests
bun test

# Lint and format
bun run lint:fix

# Type check
bun run typecheck

Troubleshooting

"The OAuth client was not found" (Error 401: invalid_client)

Ensure MCP_GKEEP_CLIENT_ID and MCP_GKEEP_CLIENT_SECRET are set correctly in your MCP config
Verify your OAuth credentials are valid in Google Cloud Console
After updating credentials, run /mcp in Claude Code to reconnect

"Access blocked" or "This app isn't verified"

Your Google Cloud app is in testing mode - add your email as a test user in the OAuth consent screen
Or click "Advanced" → "Go to [app name] (unsafe)" to proceed anyway

MCP server won't connect

Make sure Bun is installed: bun --version
Run the server directly to check for errors: ./bin/mcp-google-keep
Verify the path in ~/.claude.json is correct

"Authentication failed" or browser doesn't open

Ensure port 8085 (or your configured port) is not in use
Check that your firewall allows localhost connections
Try deleting ~/.mcp-google-keep/tokens.json and re-authenticating

"Permission denied" errors

The drive.file scope only allows access to files created by this app
You cannot access notes created outside of this MCP server
Use list_notes to see available notes

Token refresh issues

Delete ~/.mcp-google-keep/tokens.json to force re-authentication
Ensure your Google account still has access to Google Keep

License

MIT

MCP Servers