diff --git a/.dxtignore b/.dxtignore index 0b2fa36..869efc4 100644 --- a/.dxtignore +++ b/.dxtignore @@ -14,6 +14,7 @@ dist/ venv/ .idea/ .vscode/ +.claude/ # ---- macOS clutter ----------------------------------------------------- .DS_Store @@ -21,7 +22,6 @@ venv/ # ---- Secrets & Credentials -------------------------------------------- client_secret.json .credentials/ -*.json *.key *.pem *.p12 diff --git a/README.md b/README.md index 4587a66..aee60cc 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,15 @@ --- ### A quick plug for AI-Enhanced Docs +
+But why? -> **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. +
## 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,46 @@ 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 +
+Environment - you will configure these in Claude itself, see screenshot: +| 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. +
+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. @@ -180,7 +221,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 ``` diff --git a/google_workspace_mcp.dxt b/google_workspace_mcp.dxt index 229cd4e..83bed43 100644 Binary files a/google_workspace_mcp.dxt and b/google_workspace_mcp.dxt differ diff --git a/manifest.json b/manifest.json index 56d9cc3..b1c0199 100644 --- a/manifest.json +++ b/manifest.json @@ -2,8 +2,8 @@ "dxt_version": "0.1", "name": "workspace-mcp", "display_name": "Google Workspace MCP", - "version": "1.1.1", - "description": "Full natural language control over Google Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, and Chat through all MCP clients, AI assistants and developer tools", + "version": "1.1.5", + "description": "Full natural language control over Google Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks and Chat through all MCP clients, AI assistants and developer tools", "long_description": "A production-ready MCP server that integrates all major Google Workspace services with AI assistants. Built with FastMCP for optimal performance, featuring advanced authentication handling, service caching, and streamlined development patterns.", "author": { "name": "Taylor Wilsdon", @@ -29,32 +29,58 @@ }, "tools": [ { - "name": "Google Calendar", - "description": "Manage Google Calendar through AI with full calendar and event capability" + "name": "google_calendar", + "display_name": "Google Calendar", + "description": "Manage Google Calendar through AI with full calendar and event capability", + "category": "productivity" }, { - "name": "Google Drive", - "description": "Manage Google Drive through AI with full search, list and create capability" + "name": "google_drive", + "display_name": "Google Drive", + "description": "Manage Google Drive through AI with full search, list and create capability", + "category": "storage" }, { - "name": "Gmail", - "description": "Manage Gmail through AI with support for search, draft, send, respond and more" + "name": "gmail", + "display_name": "Gmail", + "description": "Manage Gmail through AI with support for search, draft, send, respond and more", + "category": "communication" }, { - "name": "Google Docs", - "description": "Manage Google Docs through Ai with capability to search, extract, list, create and copy - including templated variable repalcement support" + "name": "google_docs", + "display_name": "Google Docs", + "description": "Manage Google Docs through AI with capability to search, extract, list, create and copy - including templated variable replacement support", + "category": "productivity" }, { - "name": "Google Sheets", - "description": "Manage Google Sheets through AI with support for read, write, modify and create" + "name": "google_sheets", + "display_name": "Google Sheets", + "description": "Manage Google Sheets through AI with support for read, write, modify and create", + "category": "productivity" }, { - "name": "Google Forms", - "description": "Manage Google Forms through AI with support for creation, retreival, publishing, response management and more" + "name": "google_slides", + "display_name": "Google Slides", + "description": "Manage Google Slides through AI with support for creation, modification and presentation management", + "category": "productivity" }, { - "name": "Manage Google Chat through AI with support for space and DM list, get, send and search messages", - "description": "Manage Google Chat through AI with support for space and DM list, get, send and search messages" + "name": "google_forms", + "display_name": "Google Forms", + "description": "Manage Google Forms through AI with support for creation, retrieval, publishing, response management and more", + "category": "productivity" + }, + { + "name": "google_chat", + "display_name": "Google Chat", + "description": "Manage Google Chat through AI with support for space and DM list, get, send and search messages", + "category": "communication" + }, + { + "name": "google_tasks", + "display_name": "Google Tasks", + "description": "Manage Google Tasks through AI with support for task creation, management, and organization", + "category": "productivity" } ], "user_config": { @@ -64,14 +90,20 @@ "description": "OAuth 2.0 client ID from Google Cloud Console (e.g., your-client-id.apps.googleusercontent.com)", "required": false, "sensitive": false, - "default": "your-client-id.apps.googleusercontent.com" + "default": "your-client-id.apps.googleusercontent.com", + "validation": { + "pattern": "^[a-zA-Z0-9-]+\\.apps\\.googleusercontent\\.com$" + } }, "GOOGLE_OAUTH_CLIENT_SECRET": { "type": "string", "title": "Google OAuth Client Secret", "description": "OAuth 2.0 client secret from Google Cloud Console", "required": false, - "sensitive": true + "sensitive": true, + "validation": { + "min_length": 24 + } }, "GOOGLE_OAUTH_REDIRECT_URI": { "type": "string", @@ -79,21 +111,28 @@ "description": "OAuth 2.0 redirect URI for authentication callback", "required": false, "sensitive": false, - "default": "http://localhost:8000/oauth2callback" + "default": "http://localhost:8000/oauth2callback", + "validation": { + "pattern": "^https?://[a-zA-Z0-9.-]+:[0-9]+/oauth2callback$" + } }, "GOOGLE_CLIENT_SECRET_PATH": { - "type": "string", + "type": "file", "title": "Google Client Secret File Path", "description": "Path to the client_secret.json file containing OAuth credentials", "required": false, - "sensitive": false + "sensitive": false, + "validation": { + "extensions": [".json"] + } }, "GOOGLE_CLIENT_SECRETS": { "type": "string", "title": "Google Client Secrets (Legacy)", "description": "Legacy environment variable for client secret file path (use GOOGLE_CLIENT_SECRET_PATH instead)", "required": false, - "sensitive": false + "sensitive": false, + "deprecated": true }, "WORKSPACE_MCP_BASE_URI": { "type": "string", @@ -101,37 +140,65 @@ "description": "Base URI for the MCP server, affects OAuth redirect URI and Gemini function calling", "required": false, "sensitive": false, - "default": "http://localhost" + "default": "http://localhost", + "validation": { + "pattern": "^https?://[a-zA-Z0-9.-]+$" + } }, "WORKSPACE_MCP_PORT": { - "type": "string", + "type": "number", "title": "Workspace MCP Port", "description": "Port number for the MCP server to listen on", "required": false, "sensitive": false, - "default": "8000" + "default": 8000, + "validation": { + "min": 1024, + "max": 65535 + } }, "OAUTHLIB_INSECURE_TRANSPORT": { - "type": "number", + "type": "boolean", "title": "OAuth Insecure Transport", - "description": "Allow OAuth over HTTP for development (set to '1' for development only)", + "description": "Allow OAuth over HTTP for development (enable for development only)", "required": false, "sensitive": false, - "default": "1" + "default": true, + "platform_overrides": { + "production": { + "default": false + } + } } }, + "permissions": { + "network": true, + "filesystem": { + "read": true, + "write": ["${config_dir}", "${temp_dir}"] + } + }, + "requirements": { + "python": ">=3.8", + "platforms": ["windows", "macos", "linux"] + }, "keywords": [ "google", "workspace", "mcp", "server", - "chat", + "calendar", "drive", "docs", "forms", "gmail", "slides", - "sheets" + "sheets", + "chat", + "tasks", + "oauth", + "productivity", + "ai-assistant" ], "license": "MIT", "repository": {