create_note

Instructions

Implementation Reference

• src/server/cli.py:79-92 (handler)

  The 'create_note' MCP tool handler function. It creates a new Google Keep note via the gkeepapi, ensures a 'keep-mcp' label exists (creating it if needed), applies it to the note, syncs, and returns the serialized note as JSON.

  @mcp.tool()
  def create_note(title: str | None = None, text: str | None = None) -> str:
      """Create a new note with title and text."""
      keep = get_client()
      note = keep.createNote(title=title, text=text)
  
      label = keep.findLabel("keep-mcp")
      if not label:
          label = keep.createLabel("keep-mcp")
  
      note.labels.add(label)
      keep.sync()
  
      return json.dumps(serialize_note(note))

• src/server/cli.py:79-79 (registration)

  The @mcp.tool() decorator on line 79 registers 'create_note' as an MCP tool with the FastMCP server.

  @mcp.tool()

• src/server/keep_api.py:10-56 (helper)

  The get_client() helper function used inside create_note to obtain the authenticated gkeepapi.Keep client instance.

  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

• src/server/keep_api.py:71-105 (helper)

  The serialize_note() helper used to convert the created note object into a JSON-serializable dict.

  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