Google Workspace MCP Server

You can run the server using different transport protocols depending on your client requirements.

Stdio (Default)

Best for Claude Desktop and local MCP clients.

uvx workspace-mcp

HTTP (Streamable)

For web interfaces, debugging, or multi-client setups. Access at http://localhost:8000/mcp/.

uvx workspace-mcp --transport streamable-http

Docker

To run via Docker with HTTP transport:

docker build -t workspace-mcp .
docker run -p 8000:8000 \
  -e GOOGLE_OAUTH_CLIENT_ID="..." \
  -e GOOGLE_OAUTH_CLIENT_SECRET="..." \
  workspace-mcp --transport streamable-http

You can run the Google Workspace MCP server using uvx. You can perform an instant run without installation, limit the server to specific services, or select a specific tool tier to manage the number of available tools.

Instant run

uvx workspace-mcp

Run with specific services only

uvx workspace-mcp --tools gmail drive calendar

Run with a specific tool tier

uvx workspace-mcp --tool-tier core

uvx workspace-mcp

# With specific tools only
uvx workspace-mcp --tools gmail drive calendar

# With tool tier
uvx workspace-mcp --tool-tier core

To enable OAuth 2.1, set the MCP_ENABLE_OAUTH21 environment variable to true. Note that OAuth 2.1 requires using the streamable-http transport mode.

If MCP_ENABLE_OAUTH21 is not set, the server uses legacy authentication. In streamable-http mode, legacy authentication binds to 127.0.0.1 by default. For remote or shared HTTP deployments, use OAuth 2.1.

# OAuth 2.1 requires HTTP transport mode
export MCP_ENABLE_OAUTH21=true
uv run main.py --transport streamable-http

Use the following patterns to manage your Apps Script lifecycle via an AI agent:

• List Projects: Use list_script_projects to see available projects and their IDs.
• Inspect Code: Use get_script_project to retrieve the full project structure, including all files (e.g., .gs, .html, and appsscript.json).
• Modify Code: Use update_script_content to add or modify JavaScript files within a project.
• Execute: Use run_script_function to test functions in development mode or production deployments.
• Deploy: Use create_deployment to create new versioned deployments for production use.

Follow these guidelines when using the Google Calendar MCP tools:

• Calendar IDs: Use list_calendars to find specific IDs. You can always use primary to refer to the user's main calendar.
• Time Formats: Always use RFC 3339 for time parameters. Date-only strings (e.g., 2026-03-19) are interpreted as midnight UTC.
• All-day Events: To create an all-day event, use date-only strings for both start_time and end_time. For an event on 20 March, use start_time="2026-03-20" and end_time="2026-03-21".
• Attendee Formats: You can provide attendees as a simple list of email strings ["alice@example.com"] or as detailed objects [{"email": "alice@example.com", "optional": true}].

Building forms

1. Call create_form to initialize the form.
2. Call batch_update_form with createItem requests to add questions and content items.

Updating existing questions

Before modifying a form, call get_form first. This allows you to retrieve the specific item IDs needed for updateItem or deleteItem requests within batch_update_form.

Checking responses

Use list_form_responses to retrieve submissions. Because answers are keyed by question ID, cross-reference the response data with the output of get_form to map answers back to their human-readable questions.

When running E2E tests on a headless machine (e.g., SSH, WSL, or CI), follow this OAuth flow:

1. Run the test script. It will print an authorization URL.
2. Open that URL in a browser on any machine with a GUI.
3. Complete the Google sign-in and authorization.
4. After authorization, the browser will redirect to http://localhost/?code=... (the page will not load; this is expected).
5. Copy the full URL from your browser's address bar.
6. Paste that URL into the terminal prompt in your headless session.

This skill is a Claude Code reusable prompt that guides AI agents through complex multi-step workflows to create well-formatted Google Docs. It prevents common formatting pitfalls like style cascading, index shifting, and list merging. To use this guidance, install it into your Claude skills directory:

mkdir -p ~/.claude/skills/managing-google-workspace/references
cp skills/managing-google-workspace/references/docs-layout-workflow.md ~/.claude/skills/managing-google-workspace/references/

Avoid duplicates

Use search_contacts to check whether a contact already exists before creating a new one. Search matches on name, email, and phone number.

Batch organisation

Use contact groups to organise contacts into categories. Create a group with manage_contact_group, then add contacts to it with the modify_members action.

Extra context

The notes field on a contact is a free-text area useful for storing context that does not fit into structured fields (e.g. how you met, preferred contact method).