google-keep-notes-mcp 0.1.2__tar.gz → 0.2.0__tar.gz

google_keep_notes_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,307 @@
+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

google_keep_notes_mcp-0.2.0/README.md

@@ -0,0 +1,289 @@
+# 🗒️ 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

{google_keep_notes_mcp-0.1.2 → google_keep_notes_mcp-0.2.0}/pyproject.toml

@@ -1,15 +1,12 @@
-[build-system]
-requires = ["setuptools>=69", "wheel"]
-build-backend = "setuptools.build_meta"
-
 [project]
 name = "google-keep-notes-mcp"
-version = "0.1.2"
-description = "MCP server for Google Keep"
+version = "0.2.0"
+description = "MCP server for Google Keep — connect Claude, Copilot & ChatGPT to Google Keep"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "gkeepapi>=0.17.1",
+    "gpsoauth>=1.1.0",
     "google-api-python-client>=2.198.0",
     "google-auth-oauthlib>=1.4.0",
     "markdown>=3.10.2",