keep-agent-mem 1.0.0__py3-none-any.whl

keep_agent_mem-1.0.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: keep-agent-mem
+Version: 1.0.0
+Summary: Agent Memory via Google Keep MCP
+Project-URL: Homepage, https://github.com/anand-92/keep-agent-mem
+Project-URL: Repository, https://github.com/anand-92/keep-agent-mem
+Author-email: Nik Anand <mntechsurvey@gmail.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: gkeepapi>=0.16.0
+Requires-Dist: python-dotenv>=1.2.2
+Description-Content-Type: text/markdown
+
+# keep-agent-mem
+
+MCP server for Google Keep that serves as cross-device memory for your agents.
+
+
+## How to use
+
+1. Add the MCP server to your MCP servers:
+
+### `config.toml` clients (Claude, Droid, Cursor)
+
+```json
+  "mcpServers": {
+    "keep-agent-mem": {
+      "command": "uvx",
+      "args": [
+        "keep-agent-mem"
+      ],
+      "env": {
+        "GOOGLE_EMAIL": "Your Google Email",
+        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
+      }
+    }
+  }
+```
+
+### `config.toml` clients (Codex, Goose, etc.)
+
+```toml
+[mcp_servers.keep_agent_mem]
+command = "uvx"
+args = ["keep-agent-mem"]
+
+[mcp_servers.keep_agent_mem.env]
+GOOGLE_EMAIL = "you@example.com"
+GOOGLE_MASTER_TOKEN = "your-master-token"
+```
+
+2. Add your credentials:
+* `GOOGLE_EMAIL`: Your Google account email address
+* `GOOGLE_MASTER_TOKEN`: Your Google account master token
+
+Check https://gkeepapi.readthedocs.io/en/latest/#obtaining-a-master-token and https://github.com/simon-weber/gpsoauth?tab=readme-ov-file#alternative-flow for more information.
+
+## Tools
+
+### Query and read tools
+* `find`: Search notes with optional filters for labels, colors, pinned, archived, and trashed
+* `get`: Get a single note by ID
+
+### Creation, update, and deletion tools
+* `create`: Create a new note with a title, text, and an associated label
+* `update`: Update a note's title and text
+* `delete`: Delete a note by ID
+
+
+
+
+## Troubleshooting
+
+* If you get "DeviceManagementRequiredOrSyncDisabled" check https://admin.google.com/ac/devices/settings/general and turn "Turn off mobile management (Unmanaged)"

keep_agent_mem-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server/__main__.py,sha256=0g3iknXOS9gZUcpL_trgAcuCJnZZKjdsT_xt61WOVb4,60
+server/cli.py,sha256=SGWs6I_mMkXWipoYz2009eoEYeS9Smx4zRCH56y-IwQ,3586
+server/keep_api.py,sha256=joxjuBdd1oZ19Pz4mk7UOfPDU06enXNhp3VhbsjXzU0,2986
+keep_agent_mem-1.0.0.dist-info/METADATA,sha256=BxGuy--q_1GUNZ-we3n1Z-dN4MMY7b7fkyrCdy9q_Z8,2367
+keep_agent_mem-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+keep_agent_mem-1.0.0.dist-info/entry_points.txt,sha256=bVnl08MtZGn_UfRnnnmitF345sfYpe4R8nu-OCw-CWQ,51
+keep_agent_mem-1.0.0.dist-info/RECORD,,

keep_agent_mem-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

keep_agent_mem-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+keep-agent-mem = server.cli:main

server/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

server/cli.py

@@ -0,0 +1,136 @@
+import gkeepapi
+from fastmcp import FastMCP
+
+from .keep_api import get_client, serialize_note
+
+mcp = FastMCP("keep")
+
+
+def _get_note_or_raise(note_id: str):
+    keep = get_client()
+    note = keep.get(note_id)
+    if not note:
+        raise ValueError(f"Note with ID {note_id} not found")
+    return keep, note
+
+
+def _normalize_colors(colors: list[str] | None):
+    if colors is None:
+        return None
+
+    normalized_colors = []
+    for color in colors:
+        try:
+            normalized_colors.append(gkeepapi.node.ColorValue(color))
+        except ValueError as exc:
+            raise ValueError(f"Invalid color '{color}'") from exc
+
+    return normalized_colors
+
+
+@mcp.tool()
+def find(
+    query: str = "",
+    labels: list[str] | None = None,
+    colors: list[str] | None = None,
+    pinned: bool | None = None,
+    archived: bool | None = False,
+    trashed: bool = False,
+) -> list[dict]:
+    """Find notes using text and optional filters.
+
+    Args:
+        query: The search term or query string to search for in notes.
+        labels: A list of label IDs to filter the notes by.
+        colors: A list of ColorValue strings to filter by (e.g. DEFAULT, RED, CERULEAN).
+        pinned: Filter notes by pinned status. True for pinned, False for unpinned, None for both.
+        archived: Filter notes by archived status. Defaults to False.
+        trashed: Filter notes by trashed status. Defaults to False.
+    """
+    keep = get_client()
+    normalized_colors = _normalize_colors(colors)
+    notes = keep.find(
+        query=query,
+        labels=labels,
+        colors=normalized_colors,
+        pinned=pinned,
+        archived=archived,
+        trashed=trashed,
+    )
+
+    notes_data = [serialize_note(note) for note in notes]
+    return notes_data
+
+
+@mcp.tool()
+def get(note_id: str) -> dict:
+    """Get a note by ID.
+
+    Args:
+        note_id: The ID of the note to retrieve.
+    """
+    _, note = _get_note_or_raise(note_id)
+    return serialize_note(note)
+
+
+@mcp.tool()
+def create(label: str, title: str | None = None, text: str | None = None) -> dict:
+    """Create a new note with a title, text, and an associated label.
+
+    Args:
+        label: The label to apply to the note. If the user does not explicitly specify a label, the client (e.g. LLM agent) MUST use the name of the current project or repository as the label.
+        title: The title of the note.
+        text: The text content of the note.
+    """
+    keep = get_client()
+    note = keep.createNote(title=title, text=text)
+
+    keep_label = keep.findLabel(label)
+    if not keep_label:
+        keep_label = keep.createLabel(label)
+
+    note.labels.add(keep_label)
+    keep.sync()
+
+    return serialize_note(note)
+
+
+@mcp.tool()
+def update(note_id: str, title: str | None = None, text: str | None = None) -> dict:
+    """Update a note's properties.
+
+    Args:
+        note_id: The ID of the note to update.
+        title: The new title for the note, if specified.
+        text: The new body text for the note, if specified.
+    """
+    keep, note = _get_note_or_raise(note_id)
+
+    if title is not None:
+        note.title = title
+    if text is not None:
+        note.text = text
+
+    keep.sync()
+    return serialize_note(note)
+
+
+@mcp.tool()
+def delete(note_id: str) -> dict:
+    """Delete a note by ID.
+
+    Args:
+        note_id: The ID of the note to delete.
+    """
+    keep, note = _get_note_or_raise(note_id)
+    note.delete()
+    keep.sync()
+    return {"message": f"Note {note_id} marked for deletion"}
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

server/keep_api.py

@@ -0,0 +1,103 @@
+import gkeepapi
+import os
+import requests
+from dotenv import load_dotenv
+
+_keep_client = None
+
+def get_client():
+    """
+    Get or initialize the Google Keep client.
+    This ensures we only authenticate once and reuse the client.
+    
+    Returns:
+        gkeepapi.Keep: Authenticated Keep client
+    """
+    global _keep_client
+    
+    if _keep_client is not None:
+        return _keep_client
+    
+    # Load environment variables
+    load_dotenv()
+    
+    # Get credentials from environment variables
+    email = os.getenv('GOOGLE_EMAIL')
+    master_token = os.getenv('GOOGLE_MASTER_TOKEN')
+    
+    if not email or not master_token:
+        raise ValueError("Missing Google Keep credentials. Please set GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN environment variables.")
+    
+    # Initialize the Keep API
+    keep = gkeepapi.Keep()
+    
+    # Authenticate
+    try:
+        keep.authenticate(email, master_token)
+    except requests.exceptions.JSONDecodeError as exc:
+        raise RuntimeError(
+            "Google Keep API returned a non-JSON response during authentication. "
+            "This usually means the unofficial Keep API (notes/v1) is inaccessible "
+            "from this environment (HTTP 403/4xx). "
+            "Check that your GOOGLE_MASTER_TOKEN is valid and that the Keep API "
+            "is reachable from this network."
+        ) from exc
+    except gkeepapi.exception.LoginException as exc:
+        raise RuntimeError(
+            f"Google Keep login failed: {exc}. "
+            "Verify that GOOGLE_EMAIL and GOOGLE_MASTER_TOKEN are correct."
+        ) from exc
+    
+    # Store the client for reuse
+    _keep_client = keep
+    
+    return keep
+
+def serialize_label(label):
+    return {'id': label.id, 'name': label.name}
+
+
+def serialize_list_item(item):
+    return {
+        'id': item.id,
+        'text': item.text,
+        'checked': item.checked,
+        'parent_item_id': item.parent_item.id if item.parent_item else None,
+    }
+
+
+def serialize_note(note):
+    """
+    Serialize a Google Keep note into a dictionary.
+    
+    Args:
+        note: A Google Keep note object
+        
+    Returns:
+        dict: A dictionary containing the note's id, title, text, pinned status, color and labels
+    """
+    payload = {
+        'id': note.id,
+        'title': note.title,
+        'text': note.text,
+        'type': note.type.value,
+        'pinned': note.pinned,
+        'archived': note.archived,
+        'trashed': note.trashed,
+        'color': note.color.value if note.color else None,
+        'labels': [serialize_label(label) for label in note.labels.all()],
+        'collaborators': list(note.collaborators.all()),
+    }
+
+    if hasattr(note, 'items'):
+        payload['items'] = [serialize_list_item(item) for item in note.items]
+
+    payload['media'] = [
+        {
+            'blob_id': blob.id,
+            'type': blob.blob.type.value if blob.blob and blob.blob.type else None,
+        }
+        for blob in note.blobs
+    ]
+
+    return payload