# Google Workspace Code MCP
**Important: This is an alternative experiment, not my primary setup**
If you are looking for the Google Workspace integration I actually use day-to-day, use this skill instead:
- **Primary skill:** https://github.com/mitsuhiko/agent-stuff/tree/main/skills/google-workspace
This repository is an **alternative code-first MCP experiment** built around one `execute` tool.
It is intentionally aligned with the ideas in:
- **Your MCP Doesn’t Need 30 Tools: It Needs Code** — https://lucumr.pocoo.org/2025/8/18/code-mcps/
That post explores code-supported/code-first MCP design (fewer fixed tools, more programmable capability).
---
A local JavaScript/TypeScript MCP server with a **single tool**: `execute`.
`execute` runs JavaScript (or TypeScript with type stripping) and gives that code authenticated access to Google Workspace APIs.
## What this server does
- Exposes **one MCP tool**: `execute`
- Runs user-provided JavaScript/TypeScript (async function body; TS types stripped)
- Automatically performs OAuth login on first use (browser flow)
- Reuses stored tokens on subsequent calls
- Provides a small runtime API inside executed code:
- `auth` — Google OAuth client
- `google` — `googleapis` SDK root
- `workspace` — helper methods (`call`, `service`, `whoAmI`)
- `state` — persistent mutable object across calls
This follows a code-mode design: one flexible execution tool instead of many fixed tools.
## Requirements
- Node.js 20+
- Local desktop/browser access for the initial OAuth sign-in
## Install
```bash
npm install
```
## Run
```bash
npm start
```
or:
```bash
node src/server.js
```
## MCP configuration
This repo already includes `.mcp.json`:
```json
{
"mcpServers": {
"google-workspace-code": {
"type": "stdio",
"command": "node",
"args": [
"/Users/mitsuhiko/Development/workspace-mcp/src/server.js"
],
"env": {
"GOOGLE_WORKSPACE_AUTH_MODE": "cloud"
}
}
}
}
```
If you move the project, update the `args` path.
## Tool contract
### Tool name
- `execute`
### Input schema
- `script` (string, required): JavaScript/TypeScript async function body (TS type syntax is stripped before execution)
- `timeoutMs` (number, optional): execution timeout in milliseconds (default `30000`, max `300000`)
- `scopes` (string[], optional): override OAuth scopes for the call
- `resetState` (boolean, optional): clears persistent `state` before execution
### Execution environment
Your script runs as an async function body with these variables in scope:
- `auth`
- `google`
- `workspace`
- `state`
Return values are serialized and sent back as tool output.
## Example scripts
### 1) Who am I + list Drive files
```js
const me = await workspace.whoAmI();
const files = await workspace.call('drive', 'files.list', {
pageSize: 5,
fields: 'files(id,name,mimeType)'
});
state.lastEmail = me.email;
return {
user: me,
files: files.files,
remembered: state.lastEmail
};
```
### 2) List today’s calendar events
```js
const start = new Date();
start.setHours(0, 0, 0, 0);
const end = new Date(start);
end.setDate(end.getDate() + 1);
return await workspace.call('calendar', 'events.list', {
calendarId: 'primary',
timeMin: start.toISOString(),
timeMax: end.toISOString(),
singleEvents: true,
orderBy: 'startTime'
});
```
## OAuth and token storage
- First call without token triggers browser login automatically
- Default config directory: `~/.pi/google-workspace`
- Default token path: `~/.pi/google-workspace/token.json`
- Default auth mode: `cloud` (unless overridden)
### Environment variables
- `GOOGLE_WORKSPACE_CONFIG_DIR`
- `GOOGLE_WORKSPACE_CREDENTIALS`
- `GOOGLE_WORKSPACE_TOKEN`
- `GOOGLE_WORKSPACE_AUTH_MODE` (`cloud` or `local`)
- `GOOGLE_WORKSPACE_CLIENT_ID`
- `GOOGLE_WORKSPACE_CLOUD_FUNCTION_URL`
- `GOOGLE_WORKSPACE_CALLBACK_HOST`
## Security notes
- Uses Node `vm` for execution convenience, **not a hardened sandbox**.
- Treat this as trusted local tooling.
- Do not expose this server to untrusted users or networks.
