A UBI9 container wrapping the workspace-mcp PyPI package (v1.20.3), providing an HTTP MCP server for Google Workspace: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, and Apps Script.
Published as ghcr.io/kpiwko/workspace-mcp:latest.
| Host port | Container port | Endpoint |
|---|---|---|
| 17150 | 8000 | http://localhost:17150/mcp |
-
Open the Google Cloud Console and select or create a project. An existing project (e.g. from a previous
gmail-mcpsetup) can be reused. -
Enable these eight APIs:
- Gmail API
- Google Drive API
- Google Calendar API
- Google Docs API
- Google Sheets API
- Google Slides API
- Google Forms API
- Apps Script API
-
Create an OAuth 2.0 credential. Under APIs & Services > Credentials, click Create Credentials > OAuth client ID and choose Web application (not Desktop app).
-
Add the following URI under Authorized redirect URIs:
http://localhost:17150/oauth2callback -
Copy the generated Client ID and Client Secret into your
.envfile:GOOGLE_OAUTH_CLIENT_ID=<your-client-id> GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret>
Start the container and register the MCP with Claude Code:
mkdir -p ~/.config/workspace-mcp
podman compose up -d workspace-mcp
claude mcp add --transport http --scope user workspace-mcp http://localhost:17150/mcpThe first time you make a Google Workspace tool call (e.g. "list my recent emails"), workspace-mcp detects no credentials and returns an authorization URL. Click that URL to complete the Google OAuth flow in your browser. The refresh token is saved automatically to ~/.config/workspace-mcp and reused on subsequent container restarts.
If authentication fails, trigger the OAuth flow again by making any Google Workspace tool call — workspace-mcp will return a new authorization URL.
claude mcp add --transport http --scope user workspace-mcp http://localhost:17150/mcpThe WORKSPACE_MCP_TOOLS environment variable controls which tools are exposed. The default set is gmail drive calendar docs sheets slides forms appscript (appscript is the workspace-mcp tool name for Google Apps Script).
Override in compose.yaml to restrict the set:
environment:
WORKSPACE_MCP_TOOLS: "gmail drive calendar"workspace-mcp:
image: ghcr.io/kpiwko/workspace-mcp:latest
networks: [ai-stack]
ports:
- "17150:8000"
volumes:
- /Users/kpiwko/.config/workspace-mcp:/root/.config/workspace-mcp
environment:
GOOGLE_OAUTH_CLIENT_ID: ${GOOGLE_OAUTH_CLIENT_ID}
GOOGLE_OAUTH_CLIENT_SECRET: ${GOOGLE_OAUTH_CLIENT_SECRET}
restart: unless-stopped