Google Workspace MCP + Python API - Use MCP tools interactively or drive Gmail, Calendar, Drive, Docs, Sheets, Slides, and Tasks programmatically via the Python package.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Google Workspace MCP + Python API - Use MCP tools interactively or drive Gmail, Calendar, Drive, Docs, Sheets, Slides, and Tasks programmatically via the Python package.
version
1.0.0
category
integration
author
gworkspace-mcp
license
MIT
progressive_disclosure
{"entry_point":{"summary":"Two interfaces: MCP tools (Claude calls them directly) or Python API (your code calls Google APIs using stored OAuth credentials). Use MCP for interactive tasks; use Python API for automation and custom logic.","when_to_use":"Any task involving Gmail, Calendar, Drive, Docs, Sheets, Slides, or Tasks — whether Claude is performing the action or your Python code is.","quick_start":"MCP: just use the tools. Python API: `from gworkspace_mcp.auth import OAuthManager; creds = OAuthManager().get_credentials()`"}}
Claude performing an action in an interactive session
MCP tools (call directly)
Python script automating Google Workspace
Python API
Need data not covered by MCP tools
Python API with googleapiclient
Bulk/batch operations in code
Python API
Claude reading data then passing to Python logic
Both — MCP to fetch, Python to process
Embedding the MCP server in your own app
GoogleWorkspaceServer / create_server()
Authentication (Shared by Both Interfaces)
Run once per project directory:
gworkspace-mcp setup
Tokens are stored at ./.gworkspace-mcp/tokens.json (project-local).
Get Credentials for Python API
from gworkspace_mcp.auth import OAuthManager, TokenStatus
manager = OAuthManager()
# Check status before use
status, stored = manager.get_status()
# status is one of: TokenStatus.VALID, EXPIRED, MISSING, INVALID# Get google.oauth2.credentials.Credentials object
credentials = manager.get_credentials() # None if not authenticated# Auto-refresh if expired
token = await manager.refresh_if_needed()
Scopes Granted by Setup
from gworkspace_mcp.auth import GOOGLE_WORKSPACE_SCOPES
# Includes: calendar, gmail.modify, drive, documents, tasks, spreadsheets, presentations
MCP Tools Reference
MCP tools are called directly by Claude. All tools use the stored OAuth token automatically.
spreadsheet_id, sheet_id, chart_type, data_range, title
Bar/line/pie chart
Range notation:"Sheet1!A1:D10" or "A1:B5" (defaults to first sheet)
Slides (15 tools)
Tool
Key Parameters
Description
create_presentation
title
New presentation
get_presentation
presentation_id
Full presentation data
list_presentations
max_results
All presentations in Drive
get_presentation_text
presentation_id
All text content
get_slide
presentation_id, slide_id
Single slide data
add_slide
presentation_id, layout, index
New slide
delete_slide
presentation_id, slide_id
Remove slide
update_slide_text
presentation_id, slide_id, element_id, text
Replace text
add_text_box
presentation_id, slide_id, text, x, y, width, height
Add text box
add_image
presentation_id, slide_id, image_url, x, y, width, height
Embed image
format_text_in_slide
presentation_id, slide_id, element_id, bold, font_size, color
Format text
set_slide_background
presentation_id, slide_id, color
Background color
apply_slide_layout
presentation_id, slide_id, layout
Change layout
create_bulleted_list_slide
presentation_id, title, bullets[]
Slide with bullet list
add_formatted_text_box
presentation_id, slide_id, text, bold, font_size, color
Styled text box
Tasks (10 tools)
Tool
Key Parameters
Description
list_task_lists
—
All task lists
get_task_list
tasklist_id
Single task list
create_task_list
title
New task list
update_task_list
tasklist_id, title
Rename list
delete_task_list
tasklist_id
Delete list
list_tasks
tasklist_id, show_completed
Tasks in a list
get_task
tasklist_id, task_id
Single task
create_task
tasklist_id, title, notes, due
New task
update_task
tasklist_id, task_id, title, notes, due
Edit task
complete_task
tasklist_id, task_id
Mark complete
delete_task
tasklist_id, task_id
Delete task
move_task
tasklist_id, task_id, parent, previous
Reorder/reparent
Python API Usage
Use the Python API when your code (not Claude) needs to drive Google Workspace — automation scripts, data pipelines, custom integrations.
Setup
from gworkspace_mcp.auth import OAuthManager
from googleapiclient.discovery import build
manager = OAuthManager()
credentials = manager.get_credentials()
# credentials is google.oauth2.credentials.Credentials# Ready to pass to any googleapiclient service
from gworkspace_mcp.auth import OAuthManager, TokenStorage
# Both MCP server and your code share the same token storage
storage = TokenStorage() # reads .gworkspace-mcp/tokens.json
manager = OAuthManager(storage=storage)
creds = manager.get_credentials()
# No re-authentication needed — same tokens the MCP server uses
Error Handling
from gworkspace_mcp.auth import OAuthManager, TokenStatus
from googleapiclient.errors import HttpError
manager = OAuthManager()
status, stored = manager.get_status()
if status == TokenStatus.MISSING:
raise RuntimeError("Run 'gworkspace-mcp setup' first")
elif status == TokenStatus.EXPIRED:
token = await manager.refresh_if_needed()
elif status == TokenStatus.INVALID:
raise RuntimeError("Token corrupted — run 'gworkspace-mcp setup' to re-authenticate")
try:
result = service.users().messages().list(userId='me', q='...').execute()
except HttpError as e:
if e.resp.status == 401:
# Token expired mid-session — refresh and retryawait manager.refresh_if_needed()
elif e.resp.status == 429:
# Rate limited — back offimport time; time.sleep(2)
else:
raise
