google-workspace-mcp 1.0.0__py3-none-any.whl

google_workspace_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Google Workspace MCP - Google Workspace integration for Model Context Protocol."""
+
+__version__ = "1.0.0"

google_workspace_mcp/__main__.py

@@ -0,0 +1,43 @@
+"""
+Main entry point for running the MCP server via python -m google_workspace_mcp
+"""
+
+import asyncio
+
+from google_workspace_mcp import config  # noqa: F401
+from google_workspace_mcp.app import mcp  # Import instance from central location
+
+# Import all modules that register components with the FastMCP instance
+from google_workspace_mcp.prompts import calendar as calendar_prompts  # noqa: F401
+from google_workspace_mcp.prompts import drive as drive_prompts  # noqa: F401
+from google_workspace_mcp.prompts import gmail as gmail_prompts  # noqa: F401
+from google_workspace_mcp.prompts import slides as slides_prompts  # noqa: F401
+
+# Register resources
+from google_workspace_mcp.resources import calendar as calendar_resources  # noqa: F401
+from google_workspace_mcp.resources import drive as drive_resources  # noqa: F401
+from google_workspace_mcp.resources import gmail as gmail_resources  # noqa: F401
+from google_workspace_mcp.resources import sheets_resources  # noqa: F401
+from google_workspace_mcp.resources import slides as slides_resources  # noqa: F401
+
+# Register tools
+from google_workspace_mcp.tools import (  # noqa: F401
+    calendar_tools,
+    docs_tools,
+    drive_tools,
+    gmail_tools,
+    sheets_tools,
+    slides_tools,
+)
+
+
+def main():
+    """Main entry point for the MCP server."""
+    try:
+        asyncio.run(mcp.run())
+    except KeyboardInterrupt:
+        print("\nShutting down MCP server...")
+
+
+if __name__ == "__main__":
+    main()

google_workspace_mcp/app.py

@@ -0,0 +1,8 @@
+"""
+Central application instance definition.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# Central FastMCP instance
+mcp = FastMCP(name="google-workspace-mcp")

google_workspace_mcp/auth/__init__.py

@@ -0,0 +1,7 @@
+"""
+Authentication utilities for Google Workspace MCP.
+"""
+
+from .gauth import get_credentials
+
+__all__ = ["get_credentials"]

google_workspace_mcp/auth/gauth.py

@@ -0,0 +1,62 @@
+"""
+Google authentication utilities for Google Workspace MCP.
+
+Handles OAuth 2.0 authentication using environment variables.
+"""
+
+import logging
+import os
+from functools import lru_cache
+
+import google.auth.exceptions
+import google.auth.transport.requests
+from google.oauth2.credentials import Credentials
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=32)
+def get_credentials():
+    """
+    Retrieves Google OAuth credentials from environment variables.
+
+    The credentials are cached to avoid redundant processing, but will
+    be automatically refreshed when expired.
+
+    Returns:
+        google.oauth2.credentials.Credentials: Initialized credentials object.
+
+    Raises:
+        ValueError: If any of the required environment variables are missing.
+        CredentialsError: If credentials are invalid or revoked.
+    """
+    client_id = os.environ.get("GOOGLE_WORKSPACE_CLIENT_ID")
+    client_secret = os.environ.get("GOOGLE_WORKSPACE_CLIENT_SECRET")
+    refresh_token = os.environ.get("GOOGLE_WORKSPACE_REFRESH_TOKEN")
+
+    if not client_id:
+        raise ValueError("Environment variable 'GOOGLE_WORKSPACE_CLIENT_ID' is required but not set.")
+    if not client_secret:
+        raise ValueError("Environment variable 'GOOGLE_WORKSPACE_CLIENT_SECRET' is required but not set.")
+    if not refresh_token:
+        raise ValueError("Environment variable 'GOOGLE_WORKSPACE_REFRESH_TOKEN' is required but not set.")
+
+    logger.info("Successfully retrieved Google Workspace credentials from environment variables.")
+
+    try:
+        return Credentials(
+            token=None,  # Will be fetched automatically on first use
+            refresh_token=refresh_token,
+            token_uri="https://oauth2.googleapis.com/token",
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+        # The google-auth library automatically handles token refreshing
+        # when needed during API requests using the provided refresh token.
+
+    except google.auth.exceptions.RefreshError as e:
+        logger.exception("Credentials refresh failed - token may be revoked or expired")
+        raise ValueError(f"Invalid or revoked credentials: {e}") from e
+    except Exception as e:
+        logger.exception("Failed to create Credentials object")
+        raise ValueError(f"Failed to initialize credentials: {e}") from e

google_workspace_mcp/config.py

@@ -0,0 +1,60 @@
+"""
+MCP server utilities for Google Workspace integration.
+This file now contains utility functions, like parsing capabilities.
+"""
+
+import json
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+# Parse enabled capabilities from environment
+def get_enabled_capabilities() -> set[str]:
+    """
+    Get the set of enabled capabilities from environment variables.
+    Expects GOOGLE_WORKSPACE_ENABLED_CAPABILITIES to be a JSON array of strings.
+    E.g., '["drive", "gmail", "docs"]'
+
+    Returns:
+        set[str]: Enabled capability names
+    """
+    capabilities_str = os.environ.get("GOOGLE_WORKSPACE_ENABLED_CAPABILITIES", "[]")  # Default to empty JSON list string
+
+    if not capabilities_str.strip():
+        capabilities_str = "[]"  # Treat fully empty or whitespace-only string as empty list
+
+    capabilities: set[str] = set()
+    try:
+        parsed_list = json.loads(capabilities_str)
+        if isinstance(parsed_list, list) and all(isinstance(item, str) for item in parsed_list):
+            capabilities = {cap.strip().lower() for cap in parsed_list if cap.strip()}
+        else:
+            logger.warning(
+                f"GOOGLE_WORKSPACE_ENABLED_CAPABILITIES is not a valid JSON list of strings: {capabilities_str}. "
+                f"Found type: {type(parsed_list)}. All tools may be affected. "
+                'Please use format like \'["drive", "gmail"]\'.'
+            )
+            # Fallback to empty set, effectively disabling tools unless Hub ignores this
+            # Or, decide if we should raise an error or parse common old format as fallback
+            # For now, strict parsing and warning.
+    except json.JSONDecodeError:
+        logger.warning(
+            f"GOOGLE_WORKSPACE_ENABLED_CAPABILITIES is not valid JSON: {capabilities_str}. "
+            'All tools may be affected. Please use format like \'["drive", "gmail"]\'.'
+        )
+        # Fallback for non-JSON or badly formatted JSON
+        # Consider if a fallback to comma-separated parsing is desired for backward compatibility or remove.
+        # For now, strict parsing and warning.
+
+    if not capabilities:  # This condition includes empty JSON array "[]"
+        logger.warning(
+            "No GOOGLE_WORKSPACE_ENABLED_CAPABILITIES specified or list is empty. "
+            "All tools might be disabled depending on Hub filtering. "
+            "(Note: FastMCP relies on Hub filtering based on declared capabilities.)"
+        )
+    else:
+        logger.info(f"Declared Google Workspace capabilities via env var: {capabilities}")
+
+    return capabilities

google_workspace_mcp/prompts/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Prompt modules for Google Workspace."""
+
+__all__ = []

google_workspace_mcp/prompts/calendar.py

@@ -0,0 +1,36 @@
+"""
+Calendar prompts for Google Calendar operations.
+"""
+
+import logging
+
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.server.fastmcp.server import Context
+
+from google_workspace_mcp.app import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.prompt()
+async def draft_calendar_agenda(
+    event_id: str,
+    calendar_id: str = "primary",
+    ctx: Context = None,  # Add default None for ctx
+) -> list[UserMessage]:
+    """Drafts a meeting agenda based on event info (currently simulated)."""
+    logger.info(f"Executing draft_calendar_agenda prompt for event '{event_id}' on calendar '{calendar_id}'")
+    # TODO: Replace simulation with actual call to get event details via resource
+    # try:
+    #     event_details_dict = await ctx.read_resource(f"calendar://{calendar_id}/event/{event_id}")
+    #     event_details = f"Meeting: {event_details_dict.get('summary', 'No Title')}\n"
+    #     event_details += f"Time: {event_details_dict.get('start',{}).get('dateTime')} - {event_details_dict.get('end',{}).get('dateTime')}\n"
+    #     event_details += f"Description: {event_details_dict.get('description', 'N/A')}"
+    # except Exception as e:
+    #     logger.warning(f"Could not get event details for {event_id}: {e}")
+    #     event_details = f"Meeting: {event_id} on Calendar: {calendar_id} - Details unavailable."
+
+    # Simulate details for now
+    event_details = f"Meeting: {event_id} on Calendar: {calendar_id} - Details unavailable."
+
+    return [UserMessage(f"Please draft a simple meeting agenda based on the following event information:\n\n{event_details}")]

google_workspace_mcp/prompts/drive.py

@@ -0,0 +1,18 @@
+"""Drive related MCP Prompts."""
+
+import logging
+
+from mcp.server.fastmcp.prompts.base import UserMessage
+
+from google_workspace_mcp.app import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.prompt()
+async def suggest_drive_outline(topic: str) -> list[UserMessage]:
+    """Suggests a document outline for a given topic."""
+    logger.info(f"Executing suggest_drive_outline prompt for topic: {topic}")
+    return [
+        UserMessage(f"Please suggest a standard document outline (sections and subsections) for a document about: {topic}")
+    ]

google_workspace_mcp/prompts/gmail.py

@@ -0,0 +1,65 @@
+"""
+Gmail prompts for Gmail operations.
+"""
+
+import logging
+
+# Use specific types for clarity
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.server.fastmcp.server import Context
+
+from google_workspace_mcp.app import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.prompt()
+async def summarize_recent_emails(query: str, max_emails: int = 5, ctx: Context = None) -> list[UserMessage]:
+    """Summarizes recent emails based on a query."""
+    if ctx is None:
+        # This should ideally not happen if context injection works,
+        # but handle defensively for direct calls or tests.
+        logger.error("Context (ctx) is required for summarize_recent_emails but was not provided.")
+        # Return an error message or raise an exception?
+        # Raising seems more appropriate for a required dependency.
+        raise ValueError("Context (ctx) is required for this prompt.")
+
+    logger.info(f"Executing summarize_recent_emails prompt for query: '{query}', max: {max_emails}")
+
+    email_context = "No emails found or error fetching emails."
+    try:
+        # Construct resource URI - ensure query is URL-encoded if needed by framework
+        # Assuming FastMCP handles basic encoding or query is simple enough
+        resource_uri = f"gmail://search?q={query}"
+        logger.debug(f"Reading resource: {resource_uri}")
+
+        # Call the resource via context
+        email_data = await ctx.read_resource(resource_uri)
+        logger.debug(f"Resource returned: {email_data}")
+
+        if email_data and isinstance(email_data, dict) and "emails" in email_data:
+            emails = email_data["emails"]
+            if emails:
+                summary_parts = []
+                for _i, email in enumerate(emails[:max_emails]):  # Limit results
+                    subject = email.get("subject", "No Subject")
+                    sender = email.get("from", "Unknown Sender")
+                    snippet = email.get("snippet", "...")
+                    summary_parts.append(f"- From: {sender}\n  Subject: {subject}\n  Snippet: {snippet}")
+
+                if summary_parts:
+                    email_context = "\n".join(summary_parts)
+            else:
+                email_context = "No emails found matching the query."
+        elif email_data and isinstance(email_data, dict) and "message" in email_data:
+            # Handle case where resource returns a message like "No emails found"
+            email_context = email_data["message"]
+
+    except ValueError as ve:
+        logger.error(f"ValueError calling resource for email summary: {ve}")
+        email_context = f"Error: Could not fetch emails - {ve}"
+    except Exception as e:
+        logger.exception(f"Unexpected error calling resource for email summary: {e}")
+        email_context = "Error: An unexpected error occurred while fetching emails."
+
+    return [UserMessage(f"Please summarize the key points from these recent emails:\n\n{email_context}")]

google_workspace_mcp/prompts/slides.py

@@ -0,0 +1,40 @@
+"""
+Slides prompts for Google Slides operations.
+"""
+
+import logging
+
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.server.fastmcp.server import Context
+
+from google_workspace_mcp.app import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.prompt()
+async def suggest_slide_content(presentation_topic: str, slide_objective: str) -> list[UserMessage]:
+    """Suggests content for a presentation slide."""
+    logger.info(f"Executing suggest_slide_content prompt for topic '{presentation_topic}' and objective '{slide_objective}'")
+    return [
+        UserMessage(
+            f"Generate content suggestions for one presentation slide.\n"
+            f"Topic: {presentation_topic}\n"
+            f"Objective: {slide_objective}\n"
+            f"Please provide a concise Title and 3-4 bullet points."
+        )
+    ]
+
+
+@mcp.prompt()
+def create_slides_presentation(title: str, ctx: Context = None) -> list[UserMessage]:
+    """Creates a new Google Slides presentation with the specified title."""
+    if ctx is None:
+        # Context should be automatically injected by the MCP framework
+        pass
+
+    prompt_message = UserMessage(
+        role="user",
+        content=f"Create a new Google Slides presentation with the title: {title}",
+    )
+    return [prompt_message]

google_workspace_mcp/resources/__init__.py

@@ -0,0 +1,13 @@
+"""Resources for google-workspace-mcp."""
+
+from .sheets_resources import (
+    get_specific_sheet_metadata_resource,
+    get_spreadsheet_metadata_resource,
+)
+from .slides import get_markdown_deck_formatting_guide
+
+__all__ = [
+    "get_markdown_deck_formatting_guide",
+    "get_spreadsheet_metadata_resource",
+    "get_specific_sheet_metadata_resource",
+]

google_workspace_mcp/resources/calendar.py

@@ -0,0 +1,79 @@
+"""
+Calendar resources for Google Calendar data access.
+"""
+
+import logging
+from typing import Any
+
+from google_workspace_mcp.app import mcp
+from google_workspace_mcp.services.calendar import CalendarService
+
+logger = logging.getLogger(__name__)
+
+
+# --- Calendar Resource Functions --- #
+
+
+@mcp.resource("calendar://calendars/list")
+async def list_calendars() -> dict[str, Any]:
+    """
+    Lists all calendars accessible by the user.
+
+    Maps to URI: calendar://calendars/list
+
+    Returns:
+        A dictionary containing the list of calendars or an error message.
+    """
+    logger.info("Executing list_calendars resource")
+
+    calendar_service = CalendarService()
+    calendars = calendar_service.list_calendars()
+
+    if isinstance(calendars, dict) and calendars.get("error"):
+        raise ValueError(calendars.get("message", "Error listing calendars"))
+
+    if not calendars:
+        return {"message": "No calendars found."}
+
+    # Return raw service result
+    return {"count": len(calendars), "calendars": calendars}
+
+
+# Keep the existing list_calendars resource
+
+
+@mcp.resource("calendar://events/today")
+async def get_today_events() -> dict[str, Any]:
+    """
+    Get all events for today.
+
+    Maps to URI: calendar://events/today
+
+    Returns:
+        A dictionary containing the list of today's events.
+    """
+    logger.info("Executing get_today_events resource")
+
+    from datetime import datetime, timedelta
+
+    import pytz
+
+    calendar_service = CalendarService()
+
+    # Get today's start and end time in RFC3339 format
+    now = datetime.now(pytz.UTC)
+    start_of_day = datetime(now.year, now.month, now.day, 0, 0, 0, tzinfo=pytz.UTC)
+    end_of_day = start_of_day + timedelta(days=1)
+
+    time_min = start_of_day.isoformat()
+    time_max = end_of_day.isoformat()
+
+    events = calendar_service.get_events(calendar_id="primary", time_min=time_min, time_max=time_max, max_results=50)
+
+    if isinstance(events, dict) and events.get("error"):
+        raise ValueError(events.get("message", "Error getting today's events"))
+
+    if not events:
+        return {"message": "No events found for today."}
+
+    return {"count": len(events), "events": events}

google_workspace_mcp/resources/drive.py

@@ -0,0 +1,93 @@
+"""
+Drive resources for Google Drive data access.
+"""
+
+import logging
+from typing import Any
+
+from google_workspace_mcp.app import mcp
+from google_workspace_mcp.services.drive import DriveService
+
+logger = logging.getLogger(__name__)
+
+
+# --- Drive Resource Functions --- #
+
+
+@mcp.resource("drive://recent")
+async def get_recent_files() -> dict[str, Any]:
+    """
+    Get recently modified files (last 7 days).
+
+    Maps to URI: drive://recent
+
+    Returns:
+        A dictionary containing the list of recently modified files.
+    """
+    logger.info("Executing get_recent_files resource")
+
+    drive_service = DriveService()
+    # Using the existing search_files method with a fixed query
+    query = "modifiedTime > 'now-7d'"
+    files = drive_service.search_files(query=query, page_size=10)
+
+    if isinstance(files, dict) and files.get("error"):
+        raise ValueError(files.get("message", "Error getting recent files"))
+
+    if not files:
+        return {"message": "No recent files found."}
+
+    return {"count": len(files), "files": files}
+
+
+@mcp.resource("drive://shared")
+async def get_shared_files() -> dict[str, Any]:
+    """
+    Get files shared with the user.
+
+    Maps to URI: drive://shared
+
+    Returns:
+        A dictionary containing the list of shared files.
+    """
+    logger.info("Executing get_shared_files resource")
+
+    drive_service = DriveService()
+    # Using the existing search_files method with a fixed query
+    query = "sharedWithMe=true"
+    files = drive_service.search_files(query=query, page_size=10)
+
+    if isinstance(files, dict) and files.get("error"):
+        raise ValueError(files.get("message", "Error getting shared files"))
+
+    if not files:
+        return {"message": "No shared files found."}
+
+    return {"count": len(files), "files": files}
+
+
+@mcp.resource("drive://files/{file_id}/metadata")
+async def get_drive_file_metadata(file_id: str) -> dict[str, Any]:
+    """
+    Get metadata for a specific file from Google Drive.
+
+    Maps to URI: drive://files/{file_id}/metadata
+
+    Args:
+        file_id: The ID of the file to get metadata for
+
+    Returns:
+        A dictionary containing the file metadata.
+    """
+    logger.info(f"Executing get_drive_file_metadata resource for file_id: {file_id}")
+
+    if not file_id or not file_id.strip():
+        raise ValueError("File ID cannot be empty")
+
+    drive_service = DriveService()
+    metadata = drive_service.get_file_metadata(file_id=file_id)
+
+    if isinstance(metadata, dict) and metadata.get("error"):
+        raise ValueError(metadata.get("message", "Error getting file metadata"))
+
+    return metadata

google_workspace_mcp/resources/gmail.py

@@ -0,0 +1,58 @@
+"""
+Gmail resources for Gmail data access.
+"""
+
+import logging
+from typing import Any
+
+from google_workspace_mcp.app import mcp
+from google_workspace_mcp.services.gmail import GmailService
+
+logger = logging.getLogger(__name__)
+
+
+# --- Gmail Resource Functions --- #
+
+
+@mcp.resource("gmail://labels")
+async def get_gmail_labels() -> dict[str, Any]:
+    """
+    List all Gmail labels for the authenticated user.
+
+    Maps to URI: gmail://labels
+
+    Returns:
+        A dictionary containing the list of Gmail labels.
+    """
+    logger.info("Executing get_gmail_labels resource")
+
+    gmail_service = GmailService()
+    # This would require adding a get_labels method to GmailService
+    labels = gmail_service.get_labels()
+
+    if isinstance(labels, dict) and labels.get("error"):
+        raise ValueError(labels.get("message", "Error getting Gmail labels"))
+
+    return {"count": len(labels), "labels": labels}
+
+
+@mcp.resource("gmail://unread_count")
+async def get_unread_count() -> dict[str, Any]:
+    """
+    Get count of unread emails in the inbox.
+
+    Maps to URI: gmail://unread_count
+
+    Returns:
+        A dictionary containing the count of unread emails.
+    """
+    logger.info("Executing get_unread_count resource")
+
+    gmail_service = GmailService()
+    # This would require adding a get_unread_count method to GmailService
+    result = gmail_service.get_unread_count()
+
+    if isinstance(result, dict) and result.get("error"):
+        raise ValueError(result.get("message", "Error getting unread count"))
+
+    return {"unread_count": result}