# GSuite MCP Lane — Gmail search + Sheets append as MCP tools

Two scoped MCP tools that move seller-inbox rows from Gmail into Google Sheets without Zapier: `gold_gmail_search` + `gold_sheets_append`. BYOK Google OAuth, no hosted sync, no stored credentials.

Portfolio showcase extracted from private studio work. Derivative of `MarkusPfundstein/mcp-gsuite` (MIT, 489★) — original license preserved in `THIRD_PARTY_NOTICES.md`.

> Scope: the tools return honest `config_needed` stubs and wiring plans until Google OAuth is connected — no data is ever invented. Wire `googleapis` calls to go fully live.

## Tools

| Tool | What it does |
|---|---|
| `gold_gmail_search` | Search Gmail by query (`newer_than:7d seller/order/refund` default). Returns `{id, threadId, snippet}`. Without auth returns an honest `config_needed` stub — never invented data. |
| `gold_sheets_append` | Append `[[col1,col2],...]` rows to `spreadsheet_id` / `sheet_name`. Returns `config_needed` without auth. |

All tools are `gold_*` prefixed — no collision with upstream `mcp-gsuite`. A guided 2-step (search then append) lives in `src/moat.ts`; the 2 granular tools are the primary contract.

**Example (without auth — preview):**

```json
// gold_gmail_search { "query": "newer_than:7d", "max_results": 20 }
// → { "tool":"gold_gmail_search", "query":"newer_than:7d", "status":"config_needed", "hint":"Set GOOGLE_OAUTH_..." }

// gold_sheets_append { "spreadsheet_id":"1Bxi...","values":[["2026-08-22","order #123","$19"]]}
```

## Quickstart

```bash
npm install
npm run build
node dist/index.js
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "gsuite-mcp-lane": {
      "command": "node",
      "args": ["/absolute/path/to/gsuite-mcp-lane/dist/index.js"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "xxx",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "xxx"
      }
    }
  }
}
```

## BYOK setup (Google OAuth — no hosted sync)

1. Google Cloud project → enable **Gmail API** + **Google Sheets API**.
2. Create **OAuth 2.0 Client ID** → `CLIENT_ID` + `CLIENT_SECRET`.
3. Generate a **refresh token** (offline access) → `REFRESH_TOKEN` (or short-lived `ACCESS_TOKEN`).

| Var | Purpose |
|-----|---------|
| `GOOGLE_OAUTH_CLIENT_ID` | OAuth client ID |
| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth client secret |
| `GOOGLE_OAUTH_REFRESH_TOKEN` | Long-lived refresh token (preferred) |
| `GOOGLE_OAUTH_ACCESS_TOKEN` | Short-lived access token (alt) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Service-account JSON path (alt) |

## Upstream attribution

- `MarkusPfundstein/mcp-gsuite` — MIT — https://github.com/MarkusPfundstein/mcp-gsuite

Derivative code in `src/` is original work. Upstream MIT preserved in `THIRD_PARTY_NOTICES.md`.

## Stack

TypeScript · MCP SDK (stdio) · zod schemas · BYOK OAuth

## Next steps

Drive/Calendar tools from the same upstream, write-path confirmations, Smithery registry listing.

## License

MIT, Copyright 2026 Maxim Konovalov. See `LICENSE`.

## Author

Maxim Konovalov — Haifa · MCP servers + AI pipelines. More lanes + private demos on call.