Metadata-Version: 2.4
Name: google-keep-notes-mcp
Version: 0.2.0
Summary: MCP server for Google Keep — connect Claude, Copilot & ChatGPT to Google Keep
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gkeepapi>=0.17.1
Requires-Dist: gpsoauth>=1.1.0
Requires-Dist: google-api-python-client>=2.198.0
Requires-Dist: google-auth-oauthlib>=1.4.0
Requires-Dist: markdown>=3.10.2
Requires-Dist: mcp>=1.28.1
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: reportlab>=5.0.0
Dynamic: license-file

# 🗒️ Google Keep MCP Server

> Connect any AI assistant directly to your Google Keep — create, search, organize, export notes, set reminders, and more.

[![PyPI](https://img.shields.io/pypi/v/google-keep-notes-mcp?color=blue&label=PyPI)](https://pypi.org/project/google-keep-notes-mcp/)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple)](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
