google-nice-mcp

The Google Workspace MCP server that's actually nice to small local LLMs.

Why this exists

Most Google Workspace MCP servers expose 30+ tools across a dozen services (Gmail, Calendar, Docs, Sheets, Slides, Tasks, Chat, Forms…). That floods a small model's context window and wrecks tool selection — a 7B local model staring at 30 tools will pick the wrong one.

This server does the opposite. It's a focused, read-only context-gatherer: just Gmail and Drive, just 5 tools, with plain typed parameters (no Gmail/Drive query DSL to memorize) and compact plain-text output instead of raw API JSON. The point is to let your local LLM learn about your project from your mail and files — not to manage your account.

Features

• 🎯 Just 5 tools — small enough that a local model reliably picks the right one.
• 🧰 Gmail + Drive read — search and read email; search Drive by name or file content; read Docs, Sheets, Slides, PDF, Word, Excel and PowerPoint as text.
• 🗂️ Shared drives included — searches My Drive and shared/team drives together.
• 🗓️ Forgiving inputs — filter by sender / subject / keyword / file_type instead of query syntax, and write dates as dd.mm.yyyy.
• 📉 Token-cheap output — compact plain text, truncation, self-explaining errors.
• 🔒 Read-only by scope — gmail.readonly + drive.readonly. It physically cannot send, delete, or modify anything.

Tools

Tool	Purpose
gmail_search	Find emails by keyword, sender, subject, date range, or unread.
gmail_read_email	Read one full email — headers, plain-text body, attachment names.
drive_search	Find files by name, full-text content, and type, across My Drive and shared drives.
drive_read_file	Read a file's text: Google Docs/Sheets/Slides, PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx).
drive_list_shared_drives	Discover which shared drives you can access.

Friendly inputs everywhere

• Dates (gmail_search) use dd.mm.yyyy — e.g. 31.12.2026. Normalized internally to what the Gmail API requires; YYYY-MM-DD is also accepted.
• File types (drive_search) are simple aliases: doc, sheet, slides, pdf, folder.
• Bad input gets a self-explaining error, not an empty result.

1. Set up Google Cloud OAuth (one time)

1. Open the Google Cloud Console and create a project (or pick one).
2. Enable the APIs: APIs & Services → Library → enable Gmail API and Google Drive API.
3. Configure the consent screen: APIs & Services → OAuth consent screen.
   • User type External is fine for a personal account.
   • Add your Google account under Test users (so you don't need app verification).
4. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID.
   • Application type: Desktop app.
   • Download the JSON.
5. Save that JSON as ~/.config/google-nice-mcp/credentials.json (or set GOOGLE_NICE_CREDENTIALS to point at it).

2. Install & authenticate

git clone https://github.com/Schneckenhausmann/google-nice-mcp.git
cd google-nice-mcp
uv sync                       # installs into .venv
uv run google-nice-mcp-login  # opens a browser; approve read-only access

The token is cached at ~/.config/google-nice-mcp/token.json and refreshed automatically. Re-run the login only if you revoke access or change scopes.

3. Configure

Environment variables (all optional):

Variable	Default	Purpose
GOOGLE_NICE_CONFIG_DIR	~/.config/google-nice-mcp	Where credentials/token live.
GOOGLE_NICE_CREDENTIALS	<config>/credentials.json	OAuth client file path.
GOOGLE_NICE_TOKEN	<config>/token.json	Cached token path.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "google-nice": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/google-nice-mcp",
        "run",
        "google-nice-mcp"
      ]
    }
  }
}

Local LLM clients (Ollama, LM Studio, …)

Use the same command / args in whatever MCP config your client supports. The server speaks MCP over stdio, so anything that can launch a stdio MCP server works.

Example prompts

• "Find emails from anna@acme.com about the Q3 budget since 01.01.2026 and summarize them."
• "Search my Drive for files containing 'onboarding checklist' and read the most recent one."
• "What shared drives do I have access to, and which contain a file named 'roadmap'?"
• "Read the PDF spec in Drive (file id …) and list its requirements."

Develop

uv sync               # install deps
uv run google-nice-mcp  # run the server over stdio

Source layout: tools in server.py; Gmail/Drive API helpers in gmail.py / drive.py; file-text extraction in extract.py; OAuth in auth.py.

Notes

• Read-only. Nothing can be sent, deleted, or modified.
• Long files are truncated by drive_read_file's max_chars (default 20k); raise it to read more.
• Scanned/image-only PDFs have no extractable text and will say so (no OCR).

Acknowledgments

Built fresh, but inspired by excellent prior work in the Google Workspace MCP ecosystem — thank you to their authors:

• taylorwilsdon/google_workspace_mcp by Taylor Wilsdon — the most feature-complete Workspace MCP server; we drew on its Drive export-MIME mappings and native-vs-binary file handling.
• aaronsb/google-workspace-mcp by Aaron Bushnell — clean read-focused Gmail/Drive tool surface.

Full third-party license notices are in CREDITS.md.

License

MIT © 2026 Nikias Herzhauser