# 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](https://console.cloud.google.com/) 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

```bash
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

```json
{
  "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

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

Source layout: tools in [`server.py`](src/google_nice_mcp/server.py); Gmail/Drive
API helpers in [`gmail.py`](src/google_nice_mcp/gmail.py) /
[`drive.py`](src/google_nice_mcp/drive.py); file-text extraction in
[`extract.py`](src/google_nice_mcp/extract.py); OAuth in
[`auth.py`](src/google_nice_mcp/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**](https://github.com/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**](https://github.com/aaronsb/google-workspace-mcp)
  by Aaron Bushnell — clean read-focused Gmail/Drive tool surface.

Full third-party license notices are in [CREDITS.md](CREDITS.md).

## License

[MIT](LICENSE) © 2026 Nikias Herzhauser