Content
# 🗒️ Google Keep MCP Server
> Connect any AI assistant directly to your Google Keep — create, search, organize, export notes, set reminders, and more.
[](https://pypi.org/project/google-keep-notes-mcp/)
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
---
## ✨ What It Does
| | Feature | Description |
|--|---------|-------------|
| 📝 | **Notes** | Create, read, update, delete, archive notes |
| 🔍 | **Search** | Find notes by keyword instantly |
| 📌 | **Organize** | Pin notes, change colors, add labels |
| 🏷️ | **Labels** | Create, apply, remove labels — with auto-labeling |
| ⏰ | **Reminders** | Set reminders via Google Tasks integration |
| 👥 | **Collaborate** | Add or remove collaborators by email |
| 📤 | **Export** | Export any note as PDF, Word (DOCX), or Markdown |
| 📊 | **Analytics** | Get stats — total notes, labels, oldest, newest |
| 📅 | **Digest** | Daily/weekly digest of pinned and recent notes |
| 📋 | **Templates** | Pre-built templates: meeting, journal, project, shopping, ideas |
---
## 📦 Installation
```bash
pip install google-keep-notes-mcp
```
```bash
uv add google-keep-notes-mcp
```
Or run directly without installing (recommended for MCP clients):
```bash
uvx google-keep-notes-mcp
```
Requires Python 3.10+
---
## 🔐 Authentication
This package uses a **master token** obtained from your Google account session. It's a one-time setup.
> ⚠️ Use a **dedicated/dummy Google account** for safety.
### First-Time Setup
**Step 1 — Run the setup command:**
```bash
google-keep-mcp setup
```
This will open `accounts.google.com/EmbeddedSetup` in your browser automatically and guide you step by step.
**Step 2 — In the browser:**
1. Sign in with your Google account
2. Click **"I Agree"**
3. Press `F12` to open DevTools
4. Go to **Application → Cookies → accounts.google.com**
5. Find the `oauth_token` row → click it
6. At the bottom, **triple-click** the Cookie Value → `Ctrl+C` to copy
> ⚡ Do this quickly — the token expires fast. Have your terminal ready before copying.
**Step 3 — Back in terminal:**
Paste your email and the copied `oauth_token` value when prompted. Your master token is generated and saved automatically to:
```
~/.google_keep_mcp/config.env
```
You won't need to do this again unless your token expires.
---
## ⏰ Reminders Setup (Optional)
Reminders use the **Google Tasks API**. One-time setup required:
1. Go to [console.cloud.google.com](https://console.cloud.google.com) → Create a new project
2. Enable **Google Tasks API**
3. Go to **OAuth Consent Screen** → Add your Google account as a test user
4. Create **OAuth 2.0 Credentials** → Desktop App type → Download `credentials.json`
5. Place it at: `~/.google_keep_mcp/credentials.json`
First time you set a reminder, a browser window opens to authorize. After that it's fully automatic.
---
## 🖥️ Client Setup
<details>
<summary><b>Claude Desktop</b></summary>
Edit your `claude_desktop_config.json`:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"google-keep": {
"command": "uvx",
"args": ["google-keep-notes-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
Open **Cursor Settings** → **MCP** → **Add new server** → paste:
```json
{
"mcpServers": {
"google-keep": {
"command": "uvx",
"args": ["google-keep-notes-mcp"]
}
}
}
```
</details>
<details>
<summary><b>VS Code — GitHub Copilot</b></summary>
Create or edit:
- **Windows:** `%APPDATA%\Code\User\mcp.json`
- **macOS/Linux:** `~/.config/Code/User/mcp.json`
```json
{
"servers": {
"google-keep": {
"type": "stdio",
"command": "uvx",
"args": ["google-keep-notes-mcp"]
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Open **Windsurf Settings** → **MCP** → **Add server**:
```json
{
"mcpServers": {
"google-keep": {
"command": "uvx",
"args": ["google-keep-notes-mcp"]
}
}
}
```
</details>
---
## 🛠️ Tools Reference
### Notes
| Tool | Description |
|------|-------------|
| `keep_create_note` | Create a new note with title and content |
| `keep_list_notes` | List all active notes |
| `keep_get_note` | Get a specific note by ID |
| `keep_update_note` | Update title or content of a note |
| `keep_delete_note` | Delete (trash) a note |
| `keep_archive_note` | Archive a note |
| `keep_search_notes` | Search notes by keyword |
### Organization
| Tool | Description |
|------|-------------|
| `keep_pin_note` | Pin or unpin a note |
| `keep_change_color` | Change note color (red, blue, green, yellow, teal, pink, purple, gray, brown, white) |
### Labels
| Tool | Description |
|------|-------------|
| `keep_create_label` | Create a new label |
| `keep_add_label` | Add a label to a note |
| `keep_remove_label` | Remove a label from a note |
| `keep_list_labels` | List all labels |
| `keep_auto_label_note` | Auto-detect and apply labels to a single note |
| `keep_auto_label_all` | Auto-label all unlabeled notes |
### Reminders & Collaboration
| Tool | Description |
|------|-------------|
| `keep_set_reminder` | Set a reminder via Google Tasks (`YYYY-MM-DD HH:MM`) |
| `keep_add_collaborator` | Add a collaborator by email |
| `keep_remove_collaborator` | Remove a collaborator by email |
### Export
| Tool | Description |
|------|-------------|
| `keep_export_note` | Export note as PDF, DOCX, or Markdown — saved to `~/Desktop/KeepExports/` |
### Insights
| Tool | Description |
|------|-------------|
| `keep_get_analytics` | Full stats — total notes, label usage, oldest/newest, colors |
| `keep_get_weekly_digest` | Smart digest — pinned, recently updated, notes by label |
### Templates
| Tool | Description |
|------|-------------|
| `keep_list_templates` | List all available templates |
| `keep_create_from_template` | Create a note from a pre-built template |
**Available templates:** `meeting` · `journal` · `project` · `shopping` · `ideas`
---
## 💬 Example Prompts
```
Create a note titled "Weekend Plans" with a list of things to do
```
```
Search my notes for anything about Python
```
```
Set a reminder for my "Internship Application" note for tomorrow at 9am
```
```
Export my "MCP Concepts" note as a PDF
```
```
Auto-label all my notes
```
```
Give me a weekly digest of my Google Keep notes
```
```
Show me analytics about my notes
```
```
Create a meeting note for today's standup
```
```
Add collaborator friend@gmail.com to my "Project Plan" note
```
---
## ❌ Known Limitations
- **Image attachment** — Attaching images inside notes is not supported (Google's private upload endpoint is unavailable via this library)
- **Native reminder bell** — Keep's built-in reminder bell cannot be set via this method; reminders are created in Google Tasks instead (fully functional with notifications)
---
## 📄 License
MIT © Muhammad Abubakar
