Lite Google Workspace

Lightweight MCP server for Gmail and Google Calendar. Each Google account runs as an independent process on its own port.

Important safety feature: direct Gmail sends can be restricted with a per-account allowed_recipients list. The allowlist applies only to send_gmail_message; draft_gmail_message stays unrestricted so agents can prepare drafts for human review without being able to send them.

How it works

Claude Code  --HTTP-->  lite-google-workspace-mcp (port 8001)  --Google API-->  [email protected]
             --HTTP-->  lite-google-workspace-mcp (port 8002)  --Google API-->  [email protected]

• One process per Google account, each listening on a separate port
• OAuth tokens stored locally at ~/.config/lite-google-workspace-mcp/tokens/<account>.json
• Token refresh handled automatically via google-auth
• 21 tools exposed per account: Gmail (search, read, send, draft, labels, filters) + Calendar (events, free/busy, OOO, focus time)

Prerequisites

1. A GCP project with Gmail API and Google Calendar API enabled
2. An OAuth 2.0 credential (Web application type) with redirect URI http://localhost:8000/oauth2callback
3. Download the credential JSON and save it as ~/.config/lite-google-workspace-mcp/client_secret.json

Install

git clone https://github.com/WhymustIhaveaname/lite-google-workspace-mcp.git
cd lite-google-workspace-mcp
uv sync

First-time setup

1. Configure ports

Create ~/.config/lite-google-workspace-mcp/config.toml:

[accounts.myaccount]
port = 8001

[accounts.work]
port = 8002
allowed_recipients = ["[email protected]", "[email protected]"]

The account name is just a label you choose. It maps to a token file and a port.

allowed_recipients is optional. When set, send_gmail_message will only deliver to the listed addresses (checked against to/cc/bcc, case-insensitive); omit it to allow sending to anyone. Drafts are never delivered, so draft_gmail_message is not restricted by this list.

2. Authorize accounts

uv run lite-google-workspace-mcp auth myaccount

This prints an OAuth URL and opens your browser. Sign in with the Google account you want to link, grant permissions (you can skip some scopes if you want), and the token is saved locally.

Repeat for each account.

3. Start the server

Manual:

uv run lite-google-workspace-mcp serve --account myaccount

With systemd (recommended):

cp contrib/[email protected] ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now lite-google-workspace-mcp@myaccount

4. Connect to Claude Code

claude mcp add --scope user --transport http lite-gmail-myaccount http://localhost:8001/mcp

Re-authorization

If a token expires or you want to change granted scopes:

# Stop the service first (auth uses port 8000 which must be free)
systemctl --user stop lite-google-workspace-mcp@myaccount

# Re-authorize
uv run lite-google-workspace-mcp auth myaccount

# Restart
systemctl --user start lite-google-workspace-mcp@myaccount

Tokens expiring every 7 days

If the OAuth consent screen has an external user type and a Testing publishing status, Google expires every refresh token 7 days after consent (this applies to any scope beyond basic profile/email). The service then fails to start with invalid_grant: Token has been expired or revoked, and re-authorizing only resets the 7-day clock.

The fix is to publish the app to production: GCP Console > APIs & Services > OAuth consent screen > Publish app. Production refresh tokens don't expire on a timer. With restricted Gmail scopes you'll see an "unverified app" warning until verification, which is harmless for personal or self-hosted use.

Tools

Gmail (14 tools)

Tool	Description
search_gmail_messages	Search by Gmail query syntax
get_gmail_message_content	Read a single message
get_gmail_messages_content_batch	Read multiple messages
get_gmail_thread_content	Read an entire thread
get_gmail_threads_content_batch	Read multiple threads
get_gmail_attachment_content	Download attachment
send_gmail_message	Send (plain text or HTML, with attachments)
draft_gmail_message	Create a draft
list_gmail_labels	List all labels
manage_gmail_label	Create/update/delete labels
list_gmail_filters	List all filters
manage_gmail_filter	Create/delete filters
modify_gmail_message_labels	Add/remove labels on a message
batch_modify_gmail_message_labels	Bulk label modification

Calendar (7 tools)

Tool	Description
list_calendars	List all calendars
get_events	Get events by ID or time range
manage_event	Create/update/delete/RSVP to events
manage_out_of_office	Create/list/update/delete OOO blocks
manage_focus_time	Create/list/update/delete focus time
query_freebusy	Check availability
create_calendar	Create a new calendar

Development

uv sync --extra dev
uv run pytest
uv run ruff check src/