Google Workspace MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Workspace services including Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, and Chat with OAuth2 authentication.

Features

Gmail Operations: List labels, search messages, send emails, get message content
Google Drive: File management, content access, and file creation
Google Calendar: Event management and calendar operations
Google Docs: Document creation and content access
Google Sheets: Spreadsheet operations, data reading and creation
Google Slides: Presentation management and creation
Google Forms: Form creation and management
Google Tasks: Task list and task management
Google Chat: Space management and messaging
OAuth2 Authentication: Secure access via Google Access Tokens
Stateless Architecture: Each request is independent with Bearer token authentication
Service Filtering: Enable specific services as needed

Quick Start

Starting the Server

# Start HTTP server on port 30000 (default)
python google_workspace_mcp_stateless.py

# Start on custom port
python google_workspace_mcp_stateless.py --port 8080

# Start with debug logging
python google_workspace_mcp_stateless.py --log-level DEBUG

# Enable specific services only
python google_workspace_mcp_stateless.py --tools gmail,drive,calendar

# Install and run from PyPI
pip install workspace-mcp-http
workspace-mcp-http

The server provides these endpoints:

POST /mcp/ - Main MCP endpoint for tool execution
GET /health - Health check endpoint

Authentication

All requests require a Google Access Token via Authorization header:

Authorization: Bearer ya29.your-google-access-token

Set up Google OAuth2 and obtain access tokens with appropriate scopes.

Tools

The server provides 25 tools for comprehensive Google Workspace API access. Each tool requires Authorization: Bearer <token> header.

Gmail Tools

1. gmail_list_labels

List all Gmail labels.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "gmail_list_labels",
      "arguments": {}
    }
  }'

2. gmail_search_messages

Search Gmail messages.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "gmail_search_messages",
      "arguments": {
        "query": "is:unread from:important@example.com",
        "max_results": 20
      }
    }
  }'

3. gmail_get_message_content

Get detailed information about a specific Gmail message.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "gmail_get_message_content",
      "arguments": {
        "message_id": "1234567890abcdef"
      }
    }
  }'

4. gmail_send_message

Send a Gmail message.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "gmail_send_message",
      "arguments": {
        "to": "recipient@example.com",
        "subject": "Hello from Google Workspace MCP",
        "body": "This email was sent via the MCP server!"
      }
    }
  }'

Google Drive Tools

5. drive_list_files

List Google Drive files.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "tools/call",
    "params": {
      "name": "drive_list_files",
      "arguments": {
        "query": "name contains \"project\"",
        "max_results": 15
      }
    }
  }'

6. drive_get_file_content

Get Google Drive file content.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "6",
    "method": "tools/call",
    "params": {
      "name": "drive_get_file_content",
      "arguments": {
        "file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

7. drive_create_file

Create a Google Drive file.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "7",
    "method": "tools/call",
    "params": {
      "name": "drive_create_file",
      "arguments": {
        "name": "my-document.txt",
        "content": "Hello, this is my new document content!",
        "parent_folder_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

Google Calendar Tools

8. calendar_list_events

List Google Calendar events.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "8",
    "method": "tools/call",
    "params": {
      "name": "calendar_list_events",
      "arguments": {
        "max_results": 25
      }
    }
  }'

9. calendar_list_calendars

List Google Calendars.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "9",
    "method": "tools/call",
    "params": {
      "name": "calendar_list_calendars",
      "arguments": {}
    }
  }'

10. calendar_create_event

Create a Google Calendar event.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "10",
    "method": "tools/call",
    "params": {
      "name": "calendar_create_event",
      "arguments": {
        "summary": "Team Meeting",
        "start_time": "2024-01-15T10:00:00-08:00",
        "end_time": "2024-01-15T11:00:00-08:00"
      }
    }
  }'

Google Docs Tools

11. docs_get_document

Get Google Docs document.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "11",
    "method": "tools/call",
    "params": {
      "name": "docs_get_document",
      "arguments": {
        "document_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

12. docs_create_document

Create a Google Docs document.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "12",
    "method": "tools/call",
    "params": {
      "name": "docs_create_document",
      "arguments": {
        "title": "My New Document",
        "content": "This is the initial content of my document."
      }
    }
  }'

Google Sheets Tools

13. sheets_get_spreadsheet

Get Google Sheets spreadsheet.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "13",
    "method": "tools/call",
    "params": {
      "name": "sheets_get_spreadsheet",
      "arguments": {
        "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

14. sheets_read_values

Read values from Google Sheets.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "14",
    "method": "tools/call",
    "params": {
      "name": "sheets_read_values",
      "arguments": {
        "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
        "range_name": "A1:D10"
      }
    }
  }'

15. sheets_create_spreadsheet

Create a Google Sheets spreadsheet.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "15",
    "method": "tools/call",
    "params": {
      "name": "sheets_create_spreadsheet",
      "arguments": {
        "title": "My New Spreadsheet"
      }
    }
  }'

Google Slides Tools

16. slides_get_presentation

Get Google Slides presentation.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "16",
    "method": "tools/call",
    "params": {
      "name": "slides_get_presentation",
      "arguments": {
        "presentation_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

17. slides_create_presentation

Create a Google Slides presentation.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "17",
    "method": "tools/call",
    "params": {
      "name": "slides_create_presentation",
      "arguments": {
        "title": "My New Presentation"
      }
    }
  }'

Google Tasks Tools

18. tasks_list_task_lists

List Google Tasks task lists.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "18",
    "method": "tools/call",
    "params": {
      "name": "tasks_list_task_lists",
      "arguments": {}
    }
  }'

19. tasks_list_tasks

List tasks from a Google Tasks list.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "19",
    "method": "tools/call",
    "params": {
      "name": "tasks_list_tasks",
      "arguments": {
        "task_list_id": "@default"
      }
    }
  }'

20. tasks_create_task

Create a task in Google Tasks.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "20",
    "method": "tools/call",
    "params": {
      "name": "tasks_create_task",
      "arguments": {
        "task_list_id": "@default",
        "title": "Complete project documentation",
        "notes": "Review and finalize all documentation for the project"
      }
    }
  }'

Google Forms Tools

21. forms_create_form

Create a Google Form.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "21",
    "method": "tools/call",
    "params": {
      "name": "forms_create_form",
      "arguments": {
        "title": "Customer Feedback Survey"
      }
    }
  }'

22. forms_get_form

Get Google Form information.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "22",
    "method": "tools/call",
    "params": {
      "name": "forms_get_form",
      "arguments": {
        "form_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

Google Chat Tools

23. chat_list_spaces

List Google Chat spaces.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "23",
    "method": "tools/call",
    "params": {
      "name": "chat_list_spaces",
      "arguments": {}
    }
  }'

24. chat_send_message

Send a message to Google Chat.

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "24",
    "method": "tools/call",
    "params": {
      "name": "chat_send_message",
      "arguments": {
        "space_name": "spaces/AAAAxxxxxxx",
        "text": "Hello from the Google Workspace MCP Server!"
      }
    }
  }'

List Available Tools

Get the complete list of available tools:

curl -X POST http://localhost:30000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'

Installation

From PyPI

pip install workspace-mcp-http
workspace-mcp-http

From Source

pip install -r requirements.txt
python google_workspace_mcp_stateless.py

Authentication Setup

Create Google Cloud Project:
- Go to Google Cloud Console
- Create a new project or select existing
- Enable required APIs (Gmail, Drive, Calendar, etc.)
Set up OAuth2:
- Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
- Configure OAuth consent screen
- Download client configuration

Required Scopes:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/presentations
https://www.googleapis.com/auth/tasks
https://www.googleapis.com/auth/forms.body
https://www.googleapis.com/auth/chat.spaces

Get Access Token:
- Use Google OAuth2 flow to obtain access tokens
- Pass tokens via Authorization: Bearer header

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "python",
      "args": ["/path/to/google_workspace_mcp_stateless.py"],
      "env": {
        "GOOGLE_ACCESS_TOKEN": "ya29.your-google-access-token"
      }
    }
  }
}

Configuration

Environment Variables

# Optional - server will get token from Authorization header if not set
GOOGLE_ACCESS_TOKEN=ya29.your-google-access-token

# Server Configuration
PORT=30000
LOG_LEVEL=INFO

Service Filtering

Enable specific services only:

# Enable only Gmail and Drive
python google_workspace_mcp_stateless.py --tools gmail,drive

# Enable Calendar, Docs, and Sheets
python google_workspace_mcp_stateless.py --tools calendar,docs,sheets

Available services: gmail, drive, calendar, docs, sheets, slides, forms, tasks, chat

Use Cases

Email Management

Search and filter Gmail messages
Send automated emails
Manage labels and organization
Extract email content and metadata

Document Collaboration

Create and manage Google Docs
Access document content
Automate document workflows
Sync content across services

Data Analysis

Read and write Google Sheets data
Create automated reports
Manage spreadsheet operations
Export data for analysis

Project Management

Manage Google Tasks and task lists
Create calendar events and schedules
Track project milestones
Coordinate team activities

Communication

Manage Google Chat spaces
Send automated notifications
Create Google Forms for feedback
Coordinate team communications

Error Handling

The server provides detailed error messages for common issues:

401: Invalid or expired Google access token
403: Insufficient permissions or missing scopes
404: Resource not found (document, file, etc.)
429: Rate limit exceeded
500: Internal server errors

Google Workspace Concepts

File IDs

Google Drive, Docs, Sheets, and Slides use unique file IDs:

Found in URLs: https://docs.google.com/document/d/{FILE_ID}/edit
Format: Long alphanumeric string (e.g., 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms)

Resource Names

Google Chat spaces use resource names:

Format: spaces/{SPACE_ID}
Example: spaces/AAAAxxxxxxx

Time Formats

Calendar events use RFC3339 format:

Format: YYYY-MM-DDTHH:MM:SS±HH:MM
Example: 2024-01-15T10:00:00-08:00

Development

Run in Development Mode

python google_workspace_mcp_stateless.py --log-level DEBUG --port 8080

Testing

python test_token_auth.py

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.

Metadata

Release files for workspace-mcp-http 0.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for workspace-mcp-http 0.0.8
File	Size	Uploaded	Provenance
workspace_mcp_http-0.0.8.tar.gz	103.4 kB	Sep 16, 2025	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for workspace-mcp-http 0.0.8
File	Interpreter	ABI	Platform	Reset
workspace_mcp_http-0.0.8-py3-none-any.whl 134.6 kB Sep 16, 2025 Without provenance	Python 3	none	any	Details

Total release size: 238.0 kB

Release files / workspace_mcp_http-0.0.8.tar.gz

Download URL	workspace_mcp_http-0.0.8.tar.gz
Size	103.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`f48a5bdf8fcca2687a02d5452bfebdbf7710fa537b7cadfbfa7a7d109afe113e`
BLAKE2b-256 checksum How to use checksums	`c27078e9fcbda35150ef5d0c6ec4e57c064b5bd33b059a8be77aa431fafb3763`
Upload date	Sep 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.2`

Release files / workspace_mcp_http-0.0.8-py3-none-any.whl

Download URL	workspace_mcp_http-0.0.8-py3-none-any.whl
Size	134.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f14f703ba1d67bd06a53e341792dc3eaf2d136478839817a61065cba64fdc0e2`
BLAKE2b-256 checksum How to use checksums	`9700df2e7fd6fbe8eadd5b88074b205ddf8cac0c5e05c4141e2f60c015fe9a3b`
Upload date	Sep 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.2`

Security for workspace-mcp-http 0.0.8

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.