# Sheets & Drive MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives Claude direct, tool-level access to Google Drive and Google Sheets — list, search, and share Drive files; read, write, append, and create spreadsheets — all from natural-language requests instead of manual copy/paste between a chat window and a browser tab.

## Why

Claude is very good at producing structured data (reports, tables, tracked lists) but has no native way to land that output somewhere durable and shareable. MCP closes that gap: it's an open protocol for exposing a set of typed "tools" to an LLM client over a standard transport, so the model can call real APIs instead of just describing what you should go click. This project wires that protocol up to two Google Workspace APIs.

## Implementation

- **Transport**: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)'s `StdioServerTransport` — Claude Code spawns this as a local child process and talks to it over stdin/stdout. No network server, no ports, no hosting.
- **Auth**: a Google **service account** (via `googleapis`' `GoogleAuth`), not a personal OAuth login. The service account has its own Google identity, scoped to `spreadsheets` and `drive`. It can only see files that have been explicitly shared with its service-account email, and anything it *creates* is owned by the service account rather than by a personal account.
- **Tool schemas**: every tool's input is validated with [`zod`](https://www.npmjs.com/package/zod) before it reaches the Google API call, so the model gets a clear typed contract (and a clear validation error) instead of a raw HTTP failure.

### Tools exposed

| Tool | Purpose |
|---|---|
| `drive_list_files` | List files shared with the service account, optionally scoped to a folder |
| `drive_search_files` | Substring search by filename |
| `drive_get_file_metadata` | Metadata for a single file by ID |
| `drive_share_file` | Grant reader/commenter/writer access to an email — the hand-back mechanism after the service account creates something |
| `sheets_list_tabs` | List tab names/dimensions inside a spreadsheet |
| `sheets_read` | Read an A1-notation range of cell values |
| `sheets_write` | Overwrite a range of cells |
| `sheets_append` | Append rows to the end of a table |
| `sheets_create` | Create a new spreadsheet (owned by the service account until shared back) |

## Benefits

- **No manual hand-off**: spreadsheet-based reporting and data-entry workflows can be driven conversationally, end to end — Claude reads, updates, and creates sheets directly.
- **Clean permission boundary**: because auth runs through an isolated service account rather than a personal login, AI-driven actions are scoped to whatever's been deliberately shared with it, and anything it creates has to be deliberately shared *back* — there's no path for the model to silently touch the rest of a personal Drive.
- **Typed, inspectable tool surface**: the Zod schemas double as documentation for what each tool accepts, making the server's behavior predictable and easy to extend.

## Where else MCP fits

Nothing here is Google-specific — the pattern is: pick an external system with an API, wrap a narrow, well-scoped set of operations as MCP tools, authenticate with credentials no more privileged than the task requires, and hand the whole thing to an LLM client over stdio (local) or HTTP/SSE (remote). The same shape applies well beyond Sheets and Drive:

- **CRMs** (Salesforce, HubSpot) — look up accounts, log activity, update deal stages from a conversation
- **Ticketing / project trackers** (Jira, Linear, GitHub Issues) — create, triage, and update tickets without leaving the chat
- **Team communication** (Slack, email) — search history, draft and send messages, post summaries
- **Internal REST APIs and databases** — expose a handful of safe, parameterized queries or mutations instead of giving a model raw SQL access
- **File systems and document stores** — read/write scoped directories, generate and file reports
- **Browser automation** — drive a headless browser for tasks with no API at all
- **DevOps / observability** (CI status, logs, dashboards) — pull build state or metrics into a triage conversation

The common thread is scoping: MCP works best when each tool does one narrow, named thing, and the credentials behind it are no broader than that tool needs.