| Name | workspace-mcp JSON |
| Version |
1.1.5
JSON |
| download |
| home_page | None |
| Summary | Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive |
| upload_time | 2025-07-10 18:54:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
mcp
google
workspace
llm
ai
claude
model
context
protocol
server
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
# Google Workspace MCP Server <img src="https://github.com/user-attachments/assets/b89524e4-6e6e-49e6-ba77-00d6df0c6e5c" width="80" align="right" />
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/workspace-mcp/)
[](https://github.com/astral-sh/uv)
[](https://workspacemcp.com)
[](https://mseep.ai/app/eebbc4a6-0f8c-41b2-ace8-038e5516dba0)
**This is the single most feature-complete Google Workspace MCP server**
*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.*
###### Support for all free Google accounts (Gmail, Docs, Drive etc) & Google Workspace plans (Starter, Standard, Plus, Enterprise, Non Profit etc) with their expanded app options like Chat & Spaces.
</div>
<div align="center">
<a href="https://glama.ai/mcp/servers/@taylorwilsdon/google_workspace_mcp">
<img width="195" src="https://glama.ai/mcp/servers/@taylorwilsdon/google_workspace_mcp/badge" alt="Google Workspace Server MCP server" align="center"/>
</a>
<a href="https://www.pulsemcp.com/servers/taylorwilsdon-google-workspace">
<img width="456" src="https://github.com/user-attachments/assets/0794ef1a-dc1c-447d-9661-9c704d7acc9d" align="center"/>
</a>
</div>
---
**See it in action:**
<div align="center">
<video width="832" src="https://github.com/user-attachments/assets/a342ebb4-1319-4060-a974-39d202329710"></video>
</div>
---
### A quick plug for AI-Enhanced Docs
<details>
<summary>But why?</summary>
**This README was written with AI assistance, and here's why that matters**
>
> 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 7/10/25.
</details>
## Overview
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.
## Features
- **🔐 Advanced OAuth 2.0**: Secure authentication with automatic token refresh, transport-aware callback handling, session management, and centralized scope management
- **📅 Google Calendar**: Full calendar management with event CRUD operations
- **📁 Google Drive**: File operations with native Microsoft Office format support (.docx, .xlsx)
- **📧 Gmail**: Complete email management with search, send, and draft capabilities
- **📄 Google Docs**: Document operations including content extraction, creation, and comment management
- **📊 Google Sheets**: Comprehensive spreadsheet management with flexible cell operations and comment management
- **🖼️ Google Slides**: Presentation management with slide creation, updates, content manipulation, and comment management
- **📝 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
- **🔄 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
---
## 🚀 Quick Start
### 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.
```bash
# Set OAuth credentials via environment variables (recommended)
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
# Start the server with all Google Workspace tools
uvx workspace-mcp
# Start with specific tools only
uvx workspace-mcp --tools gmail drive calendar tasks
# Start in HTTP mode for debugging
uvx workspace-mcp --transport streamable-http
```
*Requires Python 3.11+ and [uvx](https://github.com/astral-sh/uv). The package is available on [PyPI](https://pypi.org/project/workspace-mcp).*
### Development Installation
For development or customization:
```bash
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
uv run main.py
```
### Prerequisites
- **Python 3.11+**
- **[uvx](https://github.com/astral-sh/uv)** (for instant installation) or [uv](https://github.com/astral-sh/uv) (for development)
- **Google Cloud Project** with OAuth 2.0 credentials
### Configuration
1. **Google Cloud Setup**:
- Create OAuth 2.0 credentials (web application) in [Google Cloud Console](https://console.cloud.google.com/)
- Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat
- Add redirect URI: `http://localhost:8000/oauth2callback`
- Configure credentials using one of these methods:
**Option A: Environment Variables (Recommended for Production)**
```bash
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback" # Optional
```
**Option B: File-based (Traditional)**
- Download credentials as `client_secret.json` in project root
- To use a different location, set `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable with the file path
**Credential Loading Priority**:
1. Environment variables (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`)
2. File specified by `GOOGLE_CLIENT_SECRET_PATH` or `GOOGLE_CLIENT_SECRETS` environment variable
3. Default file (`client_secret.json` in project root)
**Why Environment Variables?**
- ✅ Containerized deployments (Docker, Kubernetes)
- ✅ Cloud platforms (Heroku, Railway, etc.)
- ✅ CI/CD pipelines
- ✅ No secrets in version control
- ✅ Easy credential rotation
2. **Environment**:
```bash
export OAUTHLIB_INSECURE_TRANSPORT=1 # Development only
export USER_GOOGLE_EMAIL=your.email@gmail.com # Optional: Default email for auth - use this for single user setups and you won't need to set your email in system prompt for magic auth
```
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 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
```bash
# Default (stdio mode for MCP clients)
uv run main.py
# HTTP mode (for web interfaces and debugging)
uv run main.py --transport streamable-http
# Single-user mode (simplified authentication)
uv run main.py --single-user
# Selective tool registration (only register specific tools)
uv run main.py --tools gmail drive calendar tasks
uv run main.py --tools sheets docs
uv run main.py --single-user --tools gmail # Can combine with other flags
# Docker
docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http
```
**Available Tools for `--tools` flag**: `gmail`, `drive`, `calendar`, `docs`, `sheets`, `forms`, `tasks`, `chat`
### Connect to Claude Desktop
The server supports two transport modes:
#### Stdio Mode (Default - Recommended for Claude Desktop)
**Guided Setup (Recommended if not using DXT)**
```bash
python install_claude.py
```
This script automatically:
- Prompts you for your Google OAuth credentials (Client ID and Secret)
- Creates the Claude Desktop config file in the correct location
- Sets up all necessary environment variables
- No manual file editing required!
After running the script, just restart Claude Desktop and you're ready to go.
**Manual Claude Configuration (Alternative)**
1. Open Claude Desktop Settings → Developer → Edit Config
1. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
2. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the server configuration:
```json
{
"mcpServers": {
"google_workspace": {
"command": "uvx",
"args": ["workspace-mcp"],
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
"OAUTHLIB_INSECURE_TRANSPORT": "1"
}
}
}
}
```
**Get Google OAuth Credentials** (if you don't have them):
- Go to [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project and enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat
- Create OAuth 2.0 Client ID (Web application) with redirect URI: `http://localhost:8000/oauth2callback`
**Development Installation (For Contributors)**:
```json
{
"mcpServers": {
"google_workspace": {
"command": "uv",
"args": ["run", "main.py"],
"cwd": "/path/to/google_workspace_mcp",
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
"OAUTHLIB_INSECURE_TRANSPORT": "1"
}
}
}
}
```
#### HTTP Mode (For debugging or web interfaces)
If you need to use HTTP mode with Claude Desktop:
```json
{
"mcpServers": {
"google_workspace": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8000/mcp"]
}
}
}
```
*Note: Make sure to start the server with `--transport streamable-http` when using HTTP mode.*
### First-Time Authentication
The server features **transport-aware OAuth callback handling**:
- **Stdio Mode**: Automatically starts a minimal HTTP server on port 8000 for OAuth callbacks
- **HTTP Mode**: Uses the existing FastAPI server for OAuth callbacks
- **Same OAuth Flow**: Both modes use `http://localhost:8000/oauth2callback` for consistency
When calling a tool:
1. Server returns authorization URL
2. Open URL in browser and authorize
3. Server handles OAuth callback automatically (on port 8000 in both modes)
4. Retry the original request
---
## 🧰 Available Tools
> **Note**: All tools support automatic authentication via `@require_google_service()` decorators with 30-minute service caching.
### 📅 Google Calendar ([`calendar_tools.py`](gcalendar/calendar_tools.py))
| Tool | Description |
|------|-------------|
| `list_calendars` | List accessible calendars |
| `get_events` | Retrieve events with time range filtering |
| `get_event` | Fetch detailed information of a single event by ID |
| `create_event` | Create events (all-day or timed) with optional Drive file attachments |
| `modify_event` | Update existing events |
| `delete_event` | Remove events |
### 📁 Google Drive ([`drive_tools.py`](gdrive/drive_tools.py))
| Tool | Description |
|------|-------------|
| `search_drive_files` | Search files with query syntax |
| `get_drive_file_content` | Read file content (supports Office formats) |
| `list_drive_items` | List folder contents |
| `create_drive_file` | Create new files or fetch content from public URLs |
### 📧 Gmail ([`gmail_tools.py`](gmail/gmail_tools.py))
| Tool | Description |
|------|-------------|
| `search_gmail_messages` | Search with Gmail operators |
| `get_gmail_message_content` | Retrieve message content |
| `send_gmail_message` | Send emails |
| `draft_gmail_message` | Create drafts |
### 📝 Google Docs ([`docs_tools.py`](gdocs/docs_tools.py))
| Tool | Description |
|------|-------------|
| `search_docs` | Find documents by name |
| `get_doc_content` | Extract document text |
| `list_docs_in_folder` | List docs in folder |
| `create_doc` | Create new documents |
| `read_doc_comments` | Read all comments and replies |
| `create_doc_comment` | Create new comments |
| `reply_to_comment` | Reply to existing comments |
| `resolve_comment` | Resolve comments |
### 📊 Google Sheets ([`sheets_tools.py`](gsheets/sheets_tools.py))
| Tool | Description |
|------|-------------|
| `list_spreadsheets` | List accessible spreadsheets |
| `get_spreadsheet_info` | Get spreadsheet metadata |
| `read_sheet_values` | Read cell ranges |
| `modify_sheet_values` | Write/update/clear cells |
| `create_spreadsheet` | Create new spreadsheets |
| `create_sheet` | Add sheets to existing files |
| `read_sheet_comments` | Read all comments and replies |
| `create_sheet_comment` | Create new comments |
| `reply_to_sheet_comment` | Reply to existing comments |
| `resolve_sheet_comment` | Resolve comments |
### 🖼️ Google Slides ([`slides_tools.py`](gslides/slides_tools.py))
| Tool | Description |
|------|-------------|
| `create_presentation` | Create new presentations |
| `get_presentation` | Retrieve presentation details |
| `batch_update_presentation` | Apply multiple updates at once |
| `get_page` | Get specific slide information |
| `get_page_thumbnail` | Generate slide thumbnails |
| `read_presentation_comments` | Read all comments and replies |
| `create_presentation_comment` | Create new comments |
| `reply_to_presentation_comment` | Reply to existing comments |
| `resolve_presentation_comment` | Resolve comments |
### 📝 Google Forms ([`forms_tools.py`](gforms/forms_tools.py))
| Tool | Description |
|------|-------------|
| `create_form` | Create new forms with title and description |
| `get_form` | Retrieve form details, questions, and URLs |
| `set_publish_settings` | Configure form template and authentication settings |
| `get_form_response` | Get individual form response details |
| `list_form_responses` | List all responses to a form with pagination |
### ✓ Google Tasks ([`tasks_tools.py`](gtasks/tasks_tools.py))
| Tool | Description |
|------|-------------|
| `list_task_lists` | List all task lists with pagination support |
| `get_task_list` | Retrieve details of a specific task list |
| `create_task_list` | Create new task lists with custom titles |
| `update_task_list` | Modify existing task list titles |
| `delete_task_list` | Remove task lists and all contained tasks |
| `list_tasks` | List tasks in a specific list with filtering options |
| `get_task` | Retrieve detailed information about a specific task |
| `create_task` | Create new tasks with title, notes, due dates, and hierarchy |
| `update_task` | Modify task properties including title, notes, status, and due dates |
| `delete_task` | Remove tasks from task lists |
| `move_task` | Reposition tasks within lists or move between lists |
| `clear_completed_tasks` | Hide all completed tasks from a list |
### 💬 Google Chat ([`chat_tools.py`](gchat/chat_tools.py))
| Tool | Description |
|------|-------------|
| `list_spaces` | List chat spaces/rooms |
| `get_messages` | Retrieve space messages |
| `send_message` | Send messages to spaces |
| `search_messages` | Search across chat history |
---
## 🛠️ Development
### Project Structure
```
google_workspace_mcp/
├── auth/ # Authentication system with decorators
├── core/ # MCP server and utilities
├── g{service}/ # Service-specific tools
├── main.py # Server entry point
├── client_secret.json # OAuth credentials (not committed)
└── pyproject.toml # Dependencies
```
### Adding New Tools
```python
from auth.service_decorator import require_google_service
@require_google_service("drive", "drive_read") # Service + scope group
async def your_new_tool(service, param1: str, param2: int = 10):
"""Tool description"""
# service is automatically injected and cached
result = service.files().list().execute()
return result # Return native Python objects
```
### Architecture Highlights
- **Service Caching**: 30-minute TTL reduces authentication overhead
- **Scope Management**: Centralized in `SCOPE_GROUPS` for easy maintenance
- **Error Handling**: Native exceptions instead of manual error construction
- **Multi-Service Support**: `@require_multiple_services()` for complex tools
---
## 🔒 Security
- **Credentials**: Never commit `client_secret.json` or `.credentials/` directory
- **OAuth Callback**: Uses `http://localhost:8000/oauth2callback` for development (requires `OAUTHLIB_INSECURE_TRANSPORT=1`)
- **Transport-Aware Callbacks**: Stdio mode starts a minimal HTTP server only for OAuth, ensuring callbacks work in all modes
- **Production**: Use HTTPS for callback URIs and configure accordingly
- **Network Exposure**: Consider authentication when using `mcpo` over networks
- **Scope Minimization**: Tools request only necessary permissions
---
## 🌐 Integration with Open WebUI
To use this server as a tool provider within Open WebUI:
### 1. Create MCPO Configuration
Create a file named `config.json` with the following structure to have `mcpo` make the streamable HTTP endpoint available as an OpenAPI spec tool:
```json
{
"mcpServers": {
"google_workspace": {
"type": "streamablehttp",
"url": "http://localhost:8000/mcp"
}
}
}
```
### 2. Start the MCPO Server
```bash
mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
```
This command starts the `mcpo` proxy, serving your active (assuming port 8000) Google Workspace MCP on port 8001.
### 3. Configure Open WebUI
1. Navigate to your Open WebUI settings
2. Go to **"Connections"** → **"Tools"**
3. Click **"Add Tool"**
4. Enter the **Server URL**: `http://localhost:8001/google_workspace` (matching the mcpo base URL and server name from config.json)
5. If you used an `--api-key` with mcpo, enter it as the **API Key**
6. Save the configuration
The Google Workspace tools should now be available when interacting with models in Open WebUI.
---
## 📄 License
MIT License - see `LICENSE` file for details.
---
<div align="center">
<img width="810" alt="Gmail Integration" src="https://github.com/user-attachments/assets/656cea40-1f66-40c1-b94c-5a2c900c969d" />
<img width="810" alt="Calendar Management" src="https://github.com/user-attachments/assets/d3c2a834-fcca-4dc5-8990-6d6dc1d96048" />
<img width="842" alt="Batch Emails" src="https://github.com/user-attachments/assets/0876c789-7bcc-4414-a144-6c3f0aaffc06" />
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "workspace-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mcp, google, workspace, llm, ai, claude, model, context, protocol, server",
"author": null,
"author_email": "Taylor Wilsdon <taylor@taylorwilsdon.com>",
"download_url": "https://files.pythonhosted.org/packages/48/b3/8c14e2b5e0d080540f16366fb9d87dfad64c2d058bb7039224ce9dba95f5/workspace_mcp-1.1.5.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Google Workspace MCP Server <img src=\"https://github.com/user-attachments/assets/b89524e4-6e6e-49e6-ba77-00d6df0c6e5c\" width=\"80\" align=\"right\" />\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://pypi.org/project/workspace-mcp/)\n[](https://github.com/astral-sh/uv)\n[](https://workspacemcp.com)\n[](https://mseep.ai/app/eebbc4a6-0f8c-41b2-ace8-038e5516dba0)\n\n**This is the single most feature-complete Google Workspace MCP server**\n\n*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.*\n\n###### Support for all free Google accounts (Gmail, Docs, Drive etc) & Google Workspace plans (Starter, Standard, Plus, Enterprise, Non Profit etc) with their expanded app options like Chat & Spaces.\n\n</div>\n\n<div align=\"center\">\n<a href=\"https://glama.ai/mcp/servers/@taylorwilsdon/google_workspace_mcp\">\n <img width=\"195\" src=\"https://glama.ai/mcp/servers/@taylorwilsdon/google_workspace_mcp/badge\" alt=\"Google Workspace Server MCP server\" align=\"center\"/>\n</a>\n<a href=\"https://www.pulsemcp.com/servers/taylorwilsdon-google-workspace\">\n<img width=\"456\" src=\"https://github.com/user-attachments/assets/0794ef1a-dc1c-447d-9661-9c704d7acc9d\" align=\"center\"/>\n</a>\n</div>\n\n---\n\n\n**See it in action:**\n<div align=\"center\">\n <video width=\"832\" src=\"https://github.com/user-attachments/assets/a342ebb4-1319-4060-a974-39d202329710\"></video>\n</div>\n\n---\n\n### A quick plug for AI-Enhanced Docs\n<details>\n<summary>But why?</summary>\n\n**This README was written with AI assistance, and here's why that matters**\n>\n> 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.\n>\n> In this case, Sonnet 4 took a pass & a human (me) verified them 7/10/25.\n</details>\n\n## Overview\n\nA 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.\n\n## Features\n\n- **\ud83d\udd10 Advanced OAuth 2.0**: Secure authentication with automatic token refresh, transport-aware callback handling, session management, and centralized scope management\n- **\ud83d\udcc5 Google Calendar**: Full calendar management with event CRUD operations\n- **\ud83d\udcc1 Google Drive**: File operations with native Microsoft Office format support (.docx, .xlsx)\n- **\ud83d\udce7 Gmail**: Complete email management with search, send, and draft capabilities\n- **\ud83d\udcc4 Google Docs**: Document operations including content extraction, creation, and comment management\n- **\ud83d\udcca Google Sheets**: Comprehensive spreadsheet management with flexible cell operations and comment management\n- **\ud83d\uddbc\ufe0f Google Slides**: Presentation management with slide creation, updates, content manipulation, and comment management\n- **\ud83d\udcdd Google Forms**: Form creation, retrieval, publish settings, and response management\n- **\u2713 Google Tasks**: Complete task and task list management with hierarchy, due dates, and status tracking\n- **\ud83d\udcac Google Chat**: Space management and messaging capabilities\n- **\ud83d\udd04 All Transports**: Stdio, Streamable HTTP & SSE, OpenAPI compatibility via `mcpo`\n- **\u26a1 High Performance**: Service caching, thread-safe sessions, FastMCP integration\n- **\ud83e\udde9 Developer Friendly**: Minimal boilerplate, automatic service injection, centralized configuration\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### 1. One-Click Claude Desktop Install (Recommended)\n\n1. **Download:** Grab the latest `google_workspace_mcp.dxt` from the \u201cReleases\u201d page\n2. **Install:** Double-click the file \u2013 Claude Desktop opens and prompts you to **Install**\n3. **Configure:** In Claude Desktop \u2192 **Settings \u2192 Extensions \u2192 Google Workspace MCP**, paste your Google OAuth credentials\n4. **Use it:** Start a new Claude chat and call any Google Workspace tool \ud83c\udf89\n\n>\n**Why DXT?**\n> Desktop Extensions (`.dxt`) bundle the server, dependencies, and manifest so users go from download \u2192 working MCP in **three clicks** \u2013 no terminal, no JSON editing, no version conflicts.\n\n#### Required Configuration\n<details>\n<summary>Environment - you will configure these in Claude itself, see screenshot:</summary>\n| Variable | Purpose |\n|----------|---------|\n| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID from Google Cloud |\n| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |\n| `USER_GOOGLE_EMAIL` *(optional)* | Default email for single-user auth |\n| `OAUTHLIB_INSECURE_TRANSPORT=1` | Development only (allows `http://` redirect) |\n\nClaude Desktop stores these securely in the OS keychain; set them once in the extension pane.\n</details>\nScreenshot here\n\n---\n\n### 2. Advanced / Cross-Platform Installation\n\nIf you\u2019re developing, deploying to servers, or using another MCP-capable client, keep reading.\n\n#### Instant CLI (uvx)\n\n```bash\n# Requires Python 3.11+ and uvx\nexport GOOGLE_OAUTH_CLIENT_ID=\"xxx\"\nexport GOOGLE_OAUTH_CLIENT_SECRET=\"yyy\"\nuvx workspace-mcp --tools gmail drive calendar\n```\n\n> 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.\n\n```bash\n# Set OAuth credentials via environment variables (recommended)\nexport GOOGLE_OAUTH_CLIENT_ID=\"your-client-id.apps.googleusercontent.com\"\nexport GOOGLE_OAUTH_CLIENT_SECRET=\"your-client-secret\"\n\n# Start the server with all Google Workspace tools\nuvx workspace-mcp\n\n# Start with specific tools only\nuvx workspace-mcp --tools gmail drive calendar tasks\n\n# Start in HTTP mode for debugging\nuvx workspace-mcp --transport streamable-http\n```\n\n*Requires Python 3.11+ and [uvx](https://github.com/astral-sh/uv). The package is available on [PyPI](https://pypi.org/project/workspace-mcp).*\n\n### Development Installation\n\nFor development or customization:\n\n```bash\ngit clone https://github.com/taylorwilsdon/google_workspace_mcp.git\ncd google_workspace_mcp\nuv run main.py\n```\n\n### Prerequisites\n\n- **Python 3.11+**\n- **[uvx](https://github.com/astral-sh/uv)** (for instant installation) or [uv](https://github.com/astral-sh/uv) (for development)\n- **Google Cloud Project** with OAuth 2.0 credentials\n\n### Configuration\n\n1. **Google Cloud Setup**:\n - Create OAuth 2.0 credentials (web application) in [Google Cloud Console](https://console.cloud.google.com/)\n - Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat\n - Add redirect URI: `http://localhost:8000/oauth2callback`\n - Configure credentials using one of these methods:\n\n **Option A: Environment Variables (Recommended for Production)**\n ```bash\n export GOOGLE_OAUTH_CLIENT_ID=\"your-client-id.apps.googleusercontent.com\"\n export GOOGLE_OAUTH_CLIENT_SECRET=\"your-client-secret\"\n export GOOGLE_OAUTH_REDIRECT_URI=\"http://localhost:8000/oauth2callback\" # Optional\n ```\n\n **Option B: File-based (Traditional)**\n - Download credentials as `client_secret.json` in project root\n - To use a different location, set `GOOGLE_CLIENT_SECRET_PATH` (or legacy `GOOGLE_CLIENT_SECRETS`) environment variable with the file path\n\n **Credential Loading Priority**:\n 1. Environment variables (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`)\n 2. File specified by `GOOGLE_CLIENT_SECRET_PATH` or `GOOGLE_CLIENT_SECRETS` environment variable\n 3. Default file (`client_secret.json` in project root)\n\n **Why Environment Variables?**\n - \u2705 Containerized deployments (Docker, Kubernetes)\n - \u2705 Cloud platforms (Heroku, Railway, etc.)\n - \u2705 CI/CD pipelines\n - \u2705 No secrets in version control\n - \u2705 Easy credential rotation\n\n2. **Environment**:\n ```bash\n export OAUTHLIB_INSECURE_TRANSPORT=1 # Development only\n export USER_GOOGLE_EMAIL=your.email@gmail.com # Optional: Default email for auth - use this for single user setups and you won't need to set your email in system prompt for magic auth\n ```\n\n3. **Server Configuration**:\n The server's base URL and port can be customized using environment variables:\n - `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.\n - `WORKSPACE_MCP_PORT`: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.\n - `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`.\n - `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\n\n### Start the Server\n\n```bash\n# Default (stdio mode for MCP clients)\nuv run main.py\n\n# HTTP mode (for web interfaces and debugging)\nuv run main.py --transport streamable-http\n\n# Single-user mode (simplified authentication)\nuv run main.py --single-user\n\n# Selective tool registration (only register specific tools)\nuv run main.py --tools gmail drive calendar tasks\nuv run main.py --tools sheets docs\nuv run main.py --single-user --tools gmail # Can combine with other flags\n\n# Docker\ndocker build -t workspace-mcp .\ndocker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http\n```\n\n**Available Tools for `--tools` flag**: `gmail`, `drive`, `calendar`, `docs`, `sheets`, `forms`, `tasks`, `chat`\n\n### Connect to Claude Desktop\n\nThe server supports two transport modes:\n\n#### Stdio Mode (Default - Recommended for Claude Desktop)\n\n**Guided Setup (Recommended if not using DXT)**\n\n```bash\npython install_claude.py\n```\n\nThis script automatically:\n- Prompts you for your Google OAuth credentials (Client ID and Secret)\n- Creates the Claude Desktop config file in the correct location\n- Sets up all necessary environment variables\n- No manual file editing required!\n\nAfter running the script, just restart Claude Desktop and you're ready to go.\n\n**Manual Claude Configuration (Alternative)**\n1. Open Claude Desktop Settings \u2192 Developer \u2192 Edit Config\n 1. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n 2. **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Add the server configuration:\n ```json\n {\n \"mcpServers\": {\n \"google_workspace\": {\n \"command\": \"uvx\",\n \"args\": [\"workspace-mcp\"],\n \"env\": {\n \"GOOGLE_OAUTH_CLIENT_ID\": \"your-client-id.apps.googleusercontent.com\",\n \"GOOGLE_OAUTH_CLIENT_SECRET\": \"your-client-secret\",\n \"OAUTHLIB_INSECURE_TRANSPORT\": \"1\"\n }\n }\n }\n }\n ```\n\n**Get Google OAuth Credentials** (if you don't have them):\n- Go to [Google Cloud Console](https://console.cloud.google.com/)\n- Create a new project and enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat\n- Create OAuth 2.0 Client ID (Web application) with redirect URI: `http://localhost:8000/oauth2callback`\n\n**Development Installation (For Contributors)**:\n```json\n{\n \"mcpServers\": {\n \"google_workspace\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"main.py\"],\n \"cwd\": \"/path/to/google_workspace_mcp\",\n \"env\": {\n \"GOOGLE_OAUTH_CLIENT_ID\": \"your-client-id.apps.googleusercontent.com\",\n \"GOOGLE_OAUTH_CLIENT_SECRET\": \"your-client-secret\",\n \"OAUTHLIB_INSECURE_TRANSPORT\": \"1\"\n }\n }\n }\n}\n```\n\n#### HTTP Mode (For debugging or web interfaces)\nIf you need to use HTTP mode with Claude Desktop:\n\n```json\n{\n \"mcpServers\": {\n \"google_workspace\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"http://localhost:8000/mcp\"]\n }\n }\n}\n```\n\n*Note: Make sure to start the server with `--transport streamable-http` when using HTTP mode.*\n\n### First-Time Authentication\n\nThe server features **transport-aware OAuth callback handling**:\n\n- **Stdio Mode**: Automatically starts a minimal HTTP server on port 8000 for OAuth callbacks\n- **HTTP Mode**: Uses the existing FastAPI server for OAuth callbacks\n- **Same OAuth Flow**: Both modes use `http://localhost:8000/oauth2callback` for consistency\n\nWhen calling a tool:\n1. Server returns authorization URL\n2. Open URL in browser and authorize\n3. Server handles OAuth callback automatically (on port 8000 in both modes)\n4. Retry the original request\n\n---\n\n## \ud83e\uddf0 Available Tools\n\n> **Note**: All tools support automatic authentication via `@require_google_service()` decorators with 30-minute service caching.\n\n### \ud83d\udcc5 Google Calendar ([`calendar_tools.py`](gcalendar/calendar_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `list_calendars` | List accessible calendars |\n| `get_events` | Retrieve events with time range filtering |\n| `get_event` | Fetch detailed information of a single event by ID |\n| `create_event` | Create events (all-day or timed) with optional Drive file attachments |\n| `modify_event` | Update existing events |\n| `delete_event` | Remove events |\n\n### \ud83d\udcc1 Google Drive ([`drive_tools.py`](gdrive/drive_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `search_drive_files` | Search files with query syntax |\n| `get_drive_file_content` | Read file content (supports Office formats) |\n| `list_drive_items` | List folder contents |\n| `create_drive_file` | Create new files or fetch content from public URLs |\n\n### \ud83d\udce7 Gmail ([`gmail_tools.py`](gmail/gmail_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `search_gmail_messages` | Search with Gmail operators |\n| `get_gmail_message_content` | Retrieve message content |\n| `send_gmail_message` | Send emails |\n| `draft_gmail_message` | Create drafts |\n\n### \ud83d\udcdd Google Docs ([`docs_tools.py`](gdocs/docs_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `search_docs` | Find documents by name |\n| `get_doc_content` | Extract document text |\n| `list_docs_in_folder` | List docs in folder |\n| `create_doc` | Create new documents |\n| `read_doc_comments` | Read all comments and replies |\n| `create_doc_comment` | Create new comments |\n| `reply_to_comment` | Reply to existing comments |\n| `resolve_comment` | Resolve comments |\n\n### \ud83d\udcca Google Sheets ([`sheets_tools.py`](gsheets/sheets_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `list_spreadsheets` | List accessible spreadsheets |\n| `get_spreadsheet_info` | Get spreadsheet metadata |\n| `read_sheet_values` | Read cell ranges |\n| `modify_sheet_values` | Write/update/clear cells |\n| `create_spreadsheet` | Create new spreadsheets |\n| `create_sheet` | Add sheets to existing files |\n| `read_sheet_comments` | Read all comments and replies |\n| `create_sheet_comment` | Create new comments |\n| `reply_to_sheet_comment` | Reply to existing comments |\n| `resolve_sheet_comment` | Resolve comments |\n\n### \ud83d\uddbc\ufe0f Google Slides ([`slides_tools.py`](gslides/slides_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `create_presentation` | Create new presentations |\n| `get_presentation` | Retrieve presentation details |\n| `batch_update_presentation` | Apply multiple updates at once |\n| `get_page` | Get specific slide information |\n| `get_page_thumbnail` | Generate slide thumbnails |\n| `read_presentation_comments` | Read all comments and replies |\n| `create_presentation_comment` | Create new comments |\n| `reply_to_presentation_comment` | Reply to existing comments |\n| `resolve_presentation_comment` | Resolve comments |\n\n### \ud83d\udcdd Google Forms ([`forms_tools.py`](gforms/forms_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `create_form` | Create new forms with title and description |\n| `get_form` | Retrieve form details, questions, and URLs |\n| `set_publish_settings` | Configure form template and authentication settings |\n| `get_form_response` | Get individual form response details |\n| `list_form_responses` | List all responses to a form with pagination |\n\n### \u2713 Google Tasks ([`tasks_tools.py`](gtasks/tasks_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `list_task_lists` | List all task lists with pagination support |\n| `get_task_list` | Retrieve details of a specific task list |\n| `create_task_list` | Create new task lists with custom titles |\n| `update_task_list` | Modify existing task list titles |\n| `delete_task_list` | Remove task lists and all contained tasks |\n| `list_tasks` | List tasks in a specific list with filtering options |\n| `get_task` | Retrieve detailed information about a specific task |\n| `create_task` | Create new tasks with title, notes, due dates, and hierarchy |\n| `update_task` | Modify task properties including title, notes, status, and due dates |\n| `delete_task` | Remove tasks from task lists |\n| `move_task` | Reposition tasks within lists or move between lists |\n| `clear_completed_tasks` | Hide all completed tasks from a list |\n\n### \ud83d\udcac Google Chat ([`chat_tools.py`](gchat/chat_tools.py))\n\n| Tool | Description |\n|------|-------------|\n| `list_spaces` | List chat spaces/rooms |\n| `get_messages` | Retrieve space messages |\n| `send_message` | Send messages to spaces |\n| `search_messages` | Search across chat history |\n\n---\n\n## \ud83d\udee0\ufe0f Development\n\n### Project Structure\n\n```\ngoogle_workspace_mcp/\n\u251c\u2500\u2500 auth/ # Authentication system with decorators\n\u251c\u2500\u2500 core/ # MCP server and utilities\n\u251c\u2500\u2500 g{service}/ # Service-specific tools\n\u251c\u2500\u2500 main.py # Server entry point\n\u251c\u2500\u2500 client_secret.json # OAuth credentials (not committed)\n\u2514\u2500\u2500 pyproject.toml # Dependencies\n```\n\n### Adding New Tools\n\n```python\nfrom auth.service_decorator import require_google_service\n\n@require_google_service(\"drive\", \"drive_read\") # Service + scope group\nasync def your_new_tool(service, param1: str, param2: int = 10):\n \"\"\"Tool description\"\"\"\n # service is automatically injected and cached\n result = service.files().list().execute()\n return result # Return native Python objects\n```\n\n### Architecture Highlights\n\n- **Service Caching**: 30-minute TTL reduces authentication overhead\n- **Scope Management**: Centralized in `SCOPE_GROUPS` for easy maintenance\n- **Error Handling**: Native exceptions instead of manual error construction\n- **Multi-Service Support**: `@require_multiple_services()` for complex tools\n\n---\n\n## \ud83d\udd12 Security\n\n- **Credentials**: Never commit `client_secret.json` or `.credentials/` directory\n- **OAuth Callback**: Uses `http://localhost:8000/oauth2callback` for development (requires `OAUTHLIB_INSECURE_TRANSPORT=1`)\n- **Transport-Aware Callbacks**: Stdio mode starts a minimal HTTP server only for OAuth, ensuring callbacks work in all modes\n- **Production**: Use HTTPS for callback URIs and configure accordingly\n- **Network Exposure**: Consider authentication when using `mcpo` over networks\n- **Scope Minimization**: Tools request only necessary permissions\n\n---\n\n## \ud83c\udf10 Integration with Open WebUI\n\nTo use this server as a tool provider within Open WebUI:\n\n### 1. Create MCPO Configuration\n\nCreate a file named `config.json` with the following structure to have `mcpo` make the streamable HTTP endpoint available as an OpenAPI spec tool:\n\n```json\n{\n \"mcpServers\": {\n \"google_workspace\": {\n \"type\": \"streamablehttp\",\n \"url\": \"http://localhost:8000/mcp\"\n }\n }\n}\n```\n\n### 2. Start the MCPO Server\n\n```bash\nmcpo --port 8001 --config config.json --api-key \"your-optional-secret-key\"\n```\n\nThis command starts the `mcpo` proxy, serving your active (assuming port 8000) Google Workspace MCP on port 8001.\n\n### 3. Configure Open WebUI\n\n1. Navigate to your Open WebUI settings\n2. Go to **\"Connections\"** \u2192 **\"Tools\"**\n3. Click **\"Add Tool\"**\n4. Enter the **Server URL**: `http://localhost:8001/google_workspace` (matching the mcpo base URL and server name from config.json)\n5. If you used an `--api-key` with mcpo, enter it as the **API Key**\n6. Save the configuration\n\nThe Google Workspace tools should now be available when interacting with models in Open WebUI.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see `LICENSE` file for details.\n\n---\n\n<div align=\"center\">\n<img width=\"810\" alt=\"Gmail Integration\" src=\"https://github.com/user-attachments/assets/656cea40-1f66-40c1-b94c-5a2c900c969d\" />\n<img width=\"810\" alt=\"Calendar Management\" src=\"https://github.com/user-attachments/assets/d3c2a834-fcca-4dc5-8990-6d6dc1d96048\" />\n<img width=\"842\" alt=\"Batch Emails\" src=\"https://github.com/user-attachments/assets/0876c789-7bcc-4414-a144-6c3f0aaffc06\" />\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive",
"version": "1.1.5",
"project_urls": {
"Changelog": "https://github.com/taylorwilsdon/google_workspace_mcp/releases",
"Documentation": "https://github.com/taylorwilsdon/google_workspace_mcp#readme",
"Homepage": "https://workspacemcp.com",
"Issues": "https://github.com/taylorwilsdon/google_workspace_mcp/issues",
"Repository": "https://github.com/taylorwilsdon/google_workspace_mcp"
},
"split_keywords": [
"mcp",
" google",
" workspace",
" llm",
" ai",
" claude",
" model",
" context",
" protocol",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3c156dc804e761135a6c655dcd0688afc9518aa5091a912471aea58f51fb62f9",
"md5": "87422212d5c16fb26a29e75578712066",
"sha256": "bc3dcc65cf7553a0a168b124913bf40f78438e42cea7e24e80e043e8bb029341"
},
"downloads": -1,
"filename": "workspace_mcp-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87422212d5c16fb26a29e75578712066",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 74868,
"upload_time": "2025-07-10T18:54:27",
"upload_time_iso_8601": "2025-07-10T18:54:27.690403Z",
"url": "https://files.pythonhosted.org/packages/3c/15/6dc804e761135a6c655dcd0688afc9518aa5091a912471aea58f51fb62f9/workspace_mcp-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "48b38c14e2b5e0d080540f16366fb9d87dfad64c2d058bb7039224ce9dba95f5",
"md5": "4765cbb4dc97c3c93ddb88f18e5aee2d",
"sha256": "0038be74d263c0350c630ab954fae5fae52202a89ea9ced21ee64422760fc50e"
},
"downloads": -1,
"filename": "workspace_mcp-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "4765cbb4dc97c3c93ddb88f18e5aee2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 73128,
"upload_time": "2025-07-10T18:54:29",
"upload_time_iso_8601": "2025-07-10T18:54:29.422999Z",
"url": "https://files.pythonhosted.org/packages/48/b3/8c14e2b5e0d080540f16366fb9d87dfad64c2d058bb7039224ce9dba95f5/workspace_mcp-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 18:54:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taylorwilsdon",
"github_project": "google_workspace_mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "workspace-mcp"
}
