workspace-mcp 1.1.4__tar.gz → 1.1.5__tar.gz

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspace-mcp
-Version: 1.1.4
+Version: 1.1.5
 Summary: Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
 Author-email: Taylor Wilsdon <taylor@taylorwilsdon.com>
 License: MIT
@@ -79,13 +79,15 @@ Dynamic: license-file
 ---
 
 ### A quick plug for AI-Enhanced Docs
+<details>
+<summary>But why?</summary>
 
-> **This README was crafted with AI assistance, and here's why that matters**
+**This README was written with AI assistance, and here's why that matters**
 >
-> As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+> As a solo dev building open source tools that many never see outside use, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
 >
-> In this case, Sonnet 4 took a pass & a human (me) verified them 6/28/25.
-
+> In this case, Sonnet 4 took a pass & a human (me) verified them 7/10/25.
+</details>
 
 ## Overview
 
@@ -103,7 +105,7 @@ A production-ready MCP server that integrates all major Google Workspace service
 - **📝 Google Forms**: Form creation, retrieval, publish settings, and response management
 - **✓ Google Tasks**: Complete task and task list management with hierarchy, due dates, and status tracking
 - **💬 Google Chat**: Space management and messaging capabilities
-- **🔄 Multiple Transports**: HTTP with SSE fallback, OpenAPI compatibility via `mcpo`
+- **🔄 All Transports**: Stdio, Streamable HTTP & SSE, OpenAPI compatibility via `mcpo`
 - **⚡ High Performance**: Service caching, thread-safe sessions, FastMCP integration
 - **🧩 Developer Friendly**: Minimal boilerplate, automatic service injection, centralized configuration
 
@@ -111,7 +113,45 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ## 🚀 Quick Start
 
-### Simplest Start (uvx - Recommended)
+### 1. One-Click Claude Desktop Install (Recommended)
+
+1. **Download:** Grab the latest `google_workspace_mcp.dxt` from the “Releases” page
+2. **Install:** Double-click the file – Claude Desktop opens and prompts you to **Install**
+3. **Configure:** In Claude Desktop → **Settings → Extensions → Google Workspace MCP**, paste your Google OAuth credentials
+4. **Use it:** Start a new Claude chat and call any Google Workspace tool 🎉
+
+>
+**Why DXT?**
+> Desktop Extensions (`.dxt`) bundle the server, dependencies, and manifest so users go from download → working MCP in **three clicks** – no terminal, no JSON editing, no version conflicts.
+
+#### Required Configuration
+<details>
+<summary>Environment - you will configure these in Claude itself, see screenshot:</summary>
+| Variable | Purpose |
+|----------|---------|
+| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |
+| `USER_GOOGLE_EMAIL` *(optional)* | Default email for single-user auth |
+| `OAUTHLIB_INSECURE_TRANSPORT=1` | Development only (allows `http://` redirect) |
+
+Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.
+</details>
+Screenshot here
+
+---
+
+### 2. Advanced / Cross-Platform Installation
+
+If you’re developing, deploying to servers, or using another MCP-capable client, keep reading.
+
+#### Instant CLI (uvx)
+
+```bash
+# Requires Python 3.11+ and uvx
+export GOOGLE_OAUTH_CLIENT_ID="xxx"
+export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
+uvx workspace-mcp --tools gmail drive calendar
+```
 
 > Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
@@ -187,9 +227,10 @@ uv run main.py
 
 3. **Server Configuration**:
    The server's base URL and port can be customized using environment variables:
-   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the server_url used for Gemini native function calling and the OAUTH_REDIRECT_URI.
+   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the `server_url` used to construct the default `OAUTH_REDIRECT_URI` if `GOOGLE_OAUTH_REDIRECT_URI` is not set.
    - `WORKSPACE_MCP_PORT`: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.
    - `USER_GOOGLE_EMAIL`: Optional default email for authentication flows. If set, the LLM won't need to specify your email when calling `start_google_auth`.
+   - `GOOGLE_OAUTH_REDIRECT_URI`: Sets an override for OAuth redirect specifically, must include a full address (i.e. include port if necessary). Use this if you want to run your OAuth redirect separately from the MCP. This is not recommended outside of very specific cases
 
 ### Start the Server
 
@@ -221,7 +262,8 @@ The server supports two transport modes:
 
 #### Stdio Mode (Default - Recommended for Claude Desktop)
 
-**Easiest Setup (Recommended)**
+**Guided Setup (Recommended if not using DXT)**
+
 ```bash
 python install_claude.py
 ```

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/README.md

@@ -37,13 +37,15 @@
 ---
 
 ### A quick plug for AI-Enhanced Docs
+<details>
+<summary>But why?</summary>
 
-> **This README was crafted with AI assistance, and here's why that matters**
+**This README was written with AI assistance, and here's why that matters**
 >
-> As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+> As a solo dev building open source tools that many never see outside use, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
 >
-> In this case, Sonnet 4 took a pass & a human (me) verified them 6/28/25.
-
+> In this case, Sonnet 4 took a pass & a human (me) verified them 7/10/25.
+</details>
 
 ## Overview
 
@@ -61,7 +63,7 @@ A production-ready MCP server that integrates all major Google Workspace service
 - **📝 Google Forms**: Form creation, retrieval, publish settings, and response management
 - **✓ Google Tasks**: Complete task and task list management with hierarchy, due dates, and status tracking
 - **💬 Google Chat**: Space management and messaging capabilities
-- **🔄 Multiple Transports**: HTTP with SSE fallback, OpenAPI compatibility via `mcpo`
+- **🔄 All Transports**: Stdio, Streamable HTTP & SSE, OpenAPI compatibility via `mcpo`
 - **⚡ High Performance**: Service caching, thread-safe sessions, FastMCP integration
 - **🧩 Developer Friendly**: Minimal boilerplate, automatic service injection, centralized configuration
 
@@ -69,7 +71,45 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ## 🚀 Quick Start
 
-### Simplest Start (uvx - Recommended)
+### 1. One-Click Claude Desktop Install (Recommended)
+
+1. **Download:** Grab the latest `google_workspace_mcp.dxt` from the “Releases” page
+2. **Install:** Double-click the file – Claude Desktop opens and prompts you to **Install**
+3. **Configure:** In Claude Desktop → **Settings → Extensions → Google Workspace MCP**, paste your Google OAuth credentials
+4. **Use it:** Start a new Claude chat and call any Google Workspace tool 🎉
+
+>
+**Why DXT?**
+> Desktop Extensions (`.dxt`) bundle the server, dependencies, and manifest so users go from download → working MCP in **three clicks** – no terminal, no JSON editing, no version conflicts.
+
+#### Required Configuration
+<details>
+<summary>Environment - you will configure these in Claude itself, see screenshot:</summary>
+| Variable | Purpose |
+|----------|---------|
+| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |
+| `USER_GOOGLE_EMAIL` *(optional)* | Default email for single-user auth |
+| `OAUTHLIB_INSECURE_TRANSPORT=1` | Development only (allows `http://` redirect) |
+
+Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.
+</details>
+Screenshot here
+
+---
+
+### 2. Advanced / Cross-Platform Installation
+
+If you’re developing, deploying to servers, or using another MCP-capable client, keep reading.
+
+#### Instant CLI (uvx)
+
+```bash
+# Requires Python 3.11+ and uvx
+export GOOGLE_OAUTH_CLIENT_ID="xxx"
+export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
+uvx workspace-mcp --tools gmail drive calendar
+```
 
 > Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
@@ -145,9 +185,10 @@ uv run main.py
 
 3. **Server Configuration**:
    The server's base URL and port can be customized using environment variables:
-   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the server_url used for Gemini native function calling and the OAUTH_REDIRECT_URI.
+   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the `server_url` used to construct the default `OAUTH_REDIRECT_URI` if `GOOGLE_OAUTH_REDIRECT_URI` is not set.
    - `WORKSPACE_MCP_PORT`: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.
    - `USER_GOOGLE_EMAIL`: Optional default email for authentication flows. If set, the LLM won't need to specify your email when calling `start_google_auth`.
+   - `GOOGLE_OAUTH_REDIRECT_URI`: Sets an override for OAuth redirect specifically, must include a full address (i.e. include port if necessary). Use this if you want to run your OAuth redirect separately from the MCP. This is not recommended outside of very specific cases
 
 ### Start the Server
 
@@ -179,7 +220,8 @@ The server supports two transport modes:
 
 #### Stdio Mode (Default - Recommended for Claude Desktop)
 
-**Easiest Setup (Recommended)**
+**Guided Setup (Recommended if not using DXT)**
+
 ```bash
 python install_claude.py
 ```

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/auth/google_auth.py

@@ -1,14 +1,16 @@
 # auth/google_auth.py
 
-import os
+import asyncio
 import json
+import jwt
 import logging
-import asyncio
-from typing import List, Optional, Tuple, Dict, Any, Callable
 import os
 
+from datetime import datetime
+from typing import List, Optional, Tuple, Dict, Any
+
 from google.oauth2.credentials import Credentials
-from google_auth_oauthlib.flow import Flow, InstalledAppFlow
+from google_auth_oauthlib.flow import Flow
 from google.auth.transport.requests import Request
 from google.auth.exceptions import RefreshError
 from googleapiclient.discovery import build
@@ -161,8 +163,6 @@ def load_credentials_from_file(
         expiry = None
         if creds_data.get("expiry"):
             try:
-                from datetime import datetime
-
                 expiry = datetime.fromisoformat(creds_data["expiry"])
             except (ValueError, TypeError) as e:
                 logger.warning(
@@ -789,8 +789,6 @@ async def get_authenticated_google_service(
         # Try to get email from credentials if needed for validation
         if credentials and credentials.id_token:
             try:
-                import jwt
-
                 # Decode without verification (just to get email for logging)
                 decoded_token = jwt.decode(
                     credentials.id_token, options={"verify_signature": False}

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/auth/oauth_callback_server.py

@@ -5,15 +5,17 @@ In streamable-http mode: Uses the existing FastAPI server
 In stdio mode: Starts a minimal HTTP server just for OAuth callbacks
 """
 
+import os
 import asyncio
 import logging
 import threading
 import time
-from typing import Optional, Dict, Any
 import socket
+import uvicorn
 
 from fastapi import FastAPI, Request
-import uvicorn
+from typing import Optional
+from urllib.parse import urlparse
 
 from auth.google_auth import handle_auth_callback, check_client_secrets
 from auth.scopes import OAUTH_STATE_TO_SESSION_ID_MAP, SCOPES
@@ -73,10 +75,11 @@ class MinimalOAuthServer:
                     logger.warning(f"OAuth callback: No MCP session ID found for state '{state}'. Auth will not be tied to a specific session.")
 
                 # Exchange code for credentials
+                redirect_uri = get_oauth_redirect_uri(port=self.port, base_uri=self.base_uri)
                 verified_user_id, credentials = handle_auth_callback(
                     scopes=SCOPES,
                     authorization_response=str(request.url),
-                    redirect_uri=f"{self.base_uri}:{self.port}/oauth2callback",
+                    redirect_uri=redirect_uri,
                     session_id=mcp_session_id
                 )
 
@@ -105,7 +108,6 @@ class MinimalOAuthServer:
         # Check if port is available
         # Extract hostname from base_uri (e.g., "http://localhost" -> "localhost")
         try:
-            from urllib.parse import urlparse
             parsed_uri = urlparse(self.base_uri)
             hostname = parsed_uri.hostname or 'localhost'
         except Exception:
@@ -179,19 +181,31 @@ class MinimalOAuthServer:
 # Global instance for stdio mode
 _minimal_oauth_server: Optional[MinimalOAuthServer] = None
 
-def get_oauth_redirect_uri(transport_mode: str = "stdio", port: int = 8000, base_uri: str = "http://localhost") -> str:
+def get_oauth_redirect_uri(port: int = 8000, base_uri: str = "http://localhost") -> str:
     """
-    Get the appropriate OAuth redirect URI based on transport mode.
+    Get the appropriate OAuth redirect URI.
+
+    Priority:
+    1. GOOGLE_OAUTH_REDIRECT_URI environment variable
+    2. Constructed from port and base URI
 
     Args:
-        transport_mode: "stdio" or "streamable-http"
         port: Port number (default 8000)
         base_uri: Base URI (default "http://localhost")
 
     Returns:
         OAuth redirect URI
     """
-    return f"{base_uri}:{port}/oauth2callback"
+    # Highest priority: Use the environment variable if it's set
+    env_redirect_uri = os.getenv("GOOGLE_OAUTH_REDIRECT_URI")
+    if env_redirect_uri:
+        logger.info(f"Using redirect URI from GOOGLE_OAUTH_REDIRECT_URI: {env_redirect_uri}")
+        return env_redirect_uri
+
+    # Fallback to constructing the URI based on server settings
+    constructed_uri = f"{base_uri}:{port}/oauth2callback"
+    logger.info(f"Constructed redirect URI: {constructed_uri}")
+    return constructed_uri
 
 def ensure_oauth_callback_available(transport_mode: str = "stdio", port: int = 8000, base_uri: str = "http://localhost") -> bool:
     """

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/core/server.py

@@ -82,7 +82,7 @@ def set_transport_mode(mode: str):
 
 def get_oauth_redirect_uri_for_current_mode() -> str:
     """Get OAuth redirect URI based on current transport mode."""
-    return get_oauth_redirect_uri(_current_transport_mode, WORKSPACE_MCP_PORT, WORKSPACE_MCP_BASE_URI)
+    return get_oauth_redirect_uri(WORKSPACE_MCP_PORT, WORKSPACE_MCP_BASE_URI)
 
 # Health check endpoint
 @server.custom_route("/health", methods=["GET"])

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/gcalendar/calendar_tools.py

@@ -12,6 +12,7 @@ from typing import List, Optional, Dict, Any
 
 from mcp import types
 from googleapiclient.errors import HttpError
+from googleapiclient.discovery import build
 
 from auth.service_decorator import require_google_service
 from core.utils import handle_http_errors
@@ -268,7 +269,6 @@ async def create_event(
     if attachments:
         # Accept both file URLs and file IDs. If a URL, extract the fileId.
         event_body["attachments"] = []
-        from googleapiclient.discovery import build
         drive_service = None
         try:
             drive_service = service._http and build("drive", "v3", http=service._http)

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/gdocs/docs_tools.py

@@ -9,7 +9,6 @@ import io
 from typing import List
 
 from mcp import types
-from googleapiclient.errors import HttpError
 from googleapiclient.http import MediaIoBaseDownload
 
 # Auth & server utilities

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/gforms/forms_tools.py

@@ -6,10 +6,9 @@ This module provides MCP tools for interacting with Google Forms API.
 
 import logging
 import asyncio
-from typing import List, Optional, Dict, Any
+from typing import Optional, Dict, Any
 
 from mcp import types
-from googleapiclient.errors import HttpError
 
 from auth.service_decorator import require_google_service
 from core.server import server
@@ -47,10 +46,10 @@ async def create_form(
             "title": title
         }
     }
-    
+
     if description:
         form_body["info"]["description"] = description
-        
+
     if document_title:
         form_body["info"]["document_title"] = document_title
 
@@ -61,7 +60,7 @@ async def create_form(
     form_id = created_form.get("formId")
     edit_url = f"https://docs.google.com/forms/d/{form_id}/edit"
     responder_url = created_form.get("responderUri", f"https://docs.google.com/forms/d/{form_id}/viewform")
-    
+
     confirmation_message = f"Successfully created form '{created_form.get('info', {}).get('title', title)}' for {user_google_email}. Form ID: {form_id}. Edit URL: {edit_url}. Responder URL: {responder_url}"
     logger.info(f"Form created successfully for {user_google_email}. ID: {form_id}")
     return confirmation_message
@@ -95,10 +94,10 @@ async def get_form(
     title = form_info.get("title", "No Title")
     description = form_info.get("description", "No Description")
     document_title = form_info.get("documentTitle", title)
-    
+
     edit_url = f"https://docs.google.com/forms/d/{form_id}/edit"
     responder_url = form.get("responderUri", f"https://docs.google.com/forms/d/{form_id}/viewform")
-    
+
     items = form.get("items", [])
     questions_summary = []
     for i, item in enumerate(items, 1):
@@ -106,9 +105,9 @@ async def get_form(
         item_type = item.get("questionItem", {}).get("question", {}).get("required", False)
         required_text = " (Required)" if item_type else ""
         questions_summary.append(f"  {i}. {item_title}{required_text}")
-    
+
     questions_text = "\n".join(questions_summary) if questions_summary else "  No questions found"
-    
+
     result = f"""Form Details for {user_google_email}:
 - Title: "{title}"
 - Description: "{description}"
@@ -118,7 +117,7 @@ async def get_form(
 - Responder URL: {responder_url}
 - Questions ({len(items)} total):
 {questions_text}"""
-    
+
     logger.info(f"Successfully retrieved form for {user_google_email}. ID: {form_id}")
     return result
 
@@ -190,7 +189,7 @@ async def get_form_response(
     response_id = response.get("responseId", "Unknown")
     create_time = response.get("createTime", "Unknown")
     last_submitted_time = response.get("lastSubmittedTime", "Unknown")
-    
+
     answers = response.get("answers", {})
     answer_details = []
     for question_id, answer_data in answers.items():
@@ -200,9 +199,9 @@ async def get_form_response(
             answer_details.append(f"  Question ID {question_id}: {answer_text}")
         else:
             answer_details.append(f"  Question ID {question_id}: No answer provided")
-    
+
     answers_text = "\n".join(answer_details) if answer_details else "  No answers found"
-    
+
     result = f"""Form Response Details for {user_google_email}:
 - Form ID: {form_id}
 - Response ID: {response_id}
@@ -210,7 +209,7 @@ async def get_form_response(
 - Last Submitted: {last_submitted_time}
 - Answers:
 {answers_text}"""
-    
+
     logger.info(f"Successfully retrieved response for {user_google_email}. Response ID: {response_id}")
     return result
 
@@ -252,7 +251,7 @@ async def list_form_responses(
 
     responses = responses_result.get("responses", [])
     next_page_token = responses_result.get("nextPageToken")
-    
+
     if not responses:
         return f"No responses found for form {form_id} for {user_google_email}."
 
@@ -261,19 +260,19 @@ async def list_form_responses(
         response_id = response.get("responseId", "Unknown")
         create_time = response.get("createTime", "Unknown")
         last_submitted_time = response.get("lastSubmittedTime", "Unknown")
-        
+
         answers_count = len(response.get("answers", {}))
         response_details.append(
             f"  {i}. Response ID: {response_id} | Created: {create_time} | Last Submitted: {last_submitted_time} | Answers: {answers_count}"
         )
 
     pagination_info = f"\nNext page token: {next_page_token}" if next_page_token else "\nNo more pages."
-    
+
     result = f"""Form Responses for {user_google_email}:
 - Form ID: {form_id}
 - Total responses returned: {len(responses)}
 - Responses:
 {chr(10).join(response_details)}{pagination_info}"""
-    
+
     logger.info(f"Successfully retrieved {len(responses)} responses for {user_google_email}. Form ID: {form_id}")
     return result

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/gmail/gmail_tools.py

@@ -13,7 +13,6 @@ from email.mime.text import MIMEText
 
 from mcp import types
 from fastapi import Body
-from googleapiclient.errors import HttpError
 
 from auth.service_decorator import require_google_service
 from core.utils import handle_http_errors

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workspace-mcp"
-version = "1.1.4"
+version = "1.1.5"
 description = "Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive"
 readme = "README.md"
 keywords = [ "mcp", "google", "workspace", "llm", "ai", "claude", "model", "context", "protocol", "server"]

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/tests/test_oauth_callback_server.py

@@ -13,7 +13,6 @@ def test_get_oauth_redirect_uri_prioritizes_env_var(monkeypatch):
 
     # Call the function with parameters that would otherwise construct a different URI
     redirect_uri = get_oauth_redirect_uri(
-        transport_mode="stdio",
         port=8888,
         base_uri="http://should-be-ignored"
     )
@@ -31,7 +30,6 @@ def test_get_oauth_redirect_uri_constructs_uri_when_env_var_is_missing(monkeypat
 
     # Call the function with specific parameters
     redirect_uri = get_oauth_redirect_uri(
-        transport_mode="stdio",
         port=9999,
         base_uri="http://localhost-test"
     )

{workspace_mcp-1.1.4 → workspace_mcp-1.1.5}/workspace_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspace-mcp
-Version: 1.1.4
+Version: 1.1.5
 Summary: Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
 Author-email: Taylor Wilsdon <taylor@taylorwilsdon.com>
 License: MIT
@@ -79,13 +79,15 @@ Dynamic: license-file
 ---
 
 ### A quick plug for AI-Enhanced Docs
+<details>
+<summary>But why?</summary>
 
-> **This README was crafted with AI assistance, and here's why that matters**
+**This README was written with AI assistance, and here's why that matters**
 >
-> As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
+> As a solo dev building open source tools that many never see outside use, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like **Roo** & **Claude Code** that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
 >
-> In this case, Sonnet 4 took a pass & a human (me) verified them 6/28/25.
-
+> In this case, Sonnet 4 took a pass & a human (me) verified them 7/10/25.
+</details>
 
 ## Overview
 
@@ -103,7 +105,7 @@ A production-ready MCP server that integrates all major Google Workspace service
 - **📝 Google Forms**: Form creation, retrieval, publish settings, and response management
 - **✓ Google Tasks**: Complete task and task list management with hierarchy, due dates, and status tracking
 - **💬 Google Chat**: Space management and messaging capabilities
-- **🔄 Multiple Transports**: HTTP with SSE fallback, OpenAPI compatibility via `mcpo`
+- **🔄 All Transports**: Stdio, Streamable HTTP & SSE, OpenAPI compatibility via `mcpo`
 - **⚡ High Performance**: Service caching, thread-safe sessions, FastMCP integration
 - **🧩 Developer Friendly**: Minimal boilerplate, automatic service injection, centralized configuration
 
@@ -111,7 +113,45 @@ A production-ready MCP server that integrates all major Google Workspace service
 
 ## 🚀 Quick Start
 
-### Simplest Start (uvx - Recommended)
+### 1. One-Click Claude Desktop Install (Recommended)
+
+1. **Download:** Grab the latest `google_workspace_mcp.dxt` from the “Releases” page
+2. **Install:** Double-click the file – Claude Desktop opens and prompts you to **Install**
+3. **Configure:** In Claude Desktop → **Settings → Extensions → Google Workspace MCP**, paste your Google OAuth credentials
+4. **Use it:** Start a new Claude chat and call any Google Workspace tool 🎉
+
+>
+**Why DXT?**
+> Desktop Extensions (`.dxt`) bundle the server, dependencies, and manifest so users go from download → working MCP in **three clicks** – no terminal, no JSON editing, no version conflicts.
+
+#### Required Configuration
+<details>
+<summary>Environment - you will configure these in Claude itself, see screenshot:</summary>
+| Variable | Purpose |
+|----------|---------|
+| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |
+| `USER_GOOGLE_EMAIL` *(optional)* | Default email for single-user auth |
+| `OAUTHLIB_INSECURE_TRANSPORT=1` | Development only (allows `http://` redirect) |
+
+Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.
+</details>
+Screenshot here
+
+---
+
+### 2. Advanced / Cross-Platform Installation
+
+If you’re developing, deploying to servers, or using another MCP-capable client, keep reading.
+
+#### Instant CLI (uvx)
+
+```bash
+# Requires Python 3.11+ and uvx
+export GOOGLE_OAUTH_CLIENT_ID="xxx"
+export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
+uvx workspace-mcp --tools gmail drive calendar
+```
 
 > Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable to point to your `client_secret.json` file.
 
@@ -187,9 +227,10 @@ uv run main.py
 
 3. **Server Configuration**:
    The server's base URL and port can be customized using environment variables:
-   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the server_url used for Gemini native function calling and the OAUTH_REDIRECT_URI.
+   - `WORKSPACE_MCP_BASE_URI`: Sets the base URI for the server (default: http://localhost). This affects the `server_url` used to construct the default `OAUTH_REDIRECT_URI` if `GOOGLE_OAUTH_REDIRECT_URI` is not set.
    - `WORKSPACE_MCP_PORT`: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.
    - `USER_GOOGLE_EMAIL`: Optional default email for authentication flows. If set, the LLM won't need to specify your email when calling `start_google_auth`.
+   - `GOOGLE_OAUTH_REDIRECT_URI`: Sets an override for OAuth redirect specifically, must include a full address (i.e. include port if necessary). Use this if you want to run your OAuth redirect separately from the MCP. This is not recommended outside of very specific cases
 
 ### Start the Server
 
@@ -221,7 +262,8 @@ The server supports two transport modes:
 
 #### Stdio Mode (Default - Recommended for Claude Desktop)
 
-**Easiest Setup (Recommended)**
+**Guided Setup (Recommended if not using DXT)**
+
 ```bash
 python install_claude.py
 ```