lite-google-workspace-mcp

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

How it works

Claude Code  --HTTP-->  lite-google-workspace-mcp (port 8001)  --Google API-->  account-A@gmail.com
             --HTTP-->  lite-google-workspace-mcp (port 8002)  --Google API-->  account-B@umd.edu

• 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 = ["boss@company.com", "team@company.com"]

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/lite-google-workspace-mcp@.service ~/.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

Tools

Gmail (13 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 (8 tools)

| Tool | Description | |------|-------------| | list_calendars | List all calendars | | get_events | Query events by time range | | manage_event | Create/update/delete events | | manage_out_of_office | Create/update/delete OOO blocks | | manage_focus_time | Create/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/