Generic Google Workspace MCP Server

A reusable Model Context Protocol (MCP) server that exposes selected Google Workspace capabilities to any MCP-compatible AI agent.

Features

• Gmail: create drafts and send emails

• Google Docs: append content to existing documents

• Agent-agnostic: works with Cursor, Claude Desktop, or any MCP client

• Secure: OAuth managed by the server; no tokens in tool inputs

• Structured responses: consistent success/error envelopes

Related MCP server: MCP Google Workspace Server

Architecture

See docs/architecture.md for the full design. The server uses a layered architecture:

MCP Layer → Validation → Services → Auth / Integrations → Google APIs

Supported MCP Tools

Prerequisites

• Node.js 20+ (required by MCP SDK v2)

• A Google Cloud project with Gmail API and Google Docs API enabled

• OAuth 2.0 credentials (Desktop or Web application)

Google Cloud Setup

1. Create a project in Google Cloud Console.

2. Enable Gmail API and Google Docs API.

3. Configure the OAuth consent screen (External or Internal).

4. Create OAuth 2.0 credentials:

   • Application type: Desktop app (for local dev) or Web application

   • Authorized redirect URI: http://localhost:3000/oauth/callback (or your chosen URI)

5. Download the client ID and client secret.

Required OAuth Scopes

The documents scope is sensitive — it allows editing any Doc the authenticated user can access. This is required because agents may append to arbitrary document IDs supplied by the user.

Local Setup

git clone <repo-url>
cd mcp-server-4
npm install
cp .env.example .env
# Edit .env with your Google OAuth credentials

Authenticate

Run the OAuth flow to store tokens locally:

# Option 1: Manual code entry
npm run auth

# Option 2: Local callback server (opens browser, captures redirect)
npm run auth -- --callback-server

Tokens are saved to GOOGLE_TOKEN_STORE_PATH (default: ./tokens.json).

Run the Server

# Development (stdio)
npm run dev

# Production build
npm run build
npm start

Environment Variables

MCP Client Configuration

Cursor

Add to your Cursor MCP settings (see examples/cursor-mcp-config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-4/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/oauth/callback",
        "GOOGLE_TOKEN_STORE_PATH": "/absolute/path/to/tokens.json",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Build first with npm run build, or use tsx for development:

"command": "npx",
"args": ["tsx", "/absolute/path/to/mcp-server-4/src/index.ts"]

Example Tool Calls

Create a draft

{
  "to": ["user@example.com"],
  "subject": "Project update",
  "body": "Hi team,\n\nHere is the latest update...",
  "bodyType": "text"
}

Send an email

{
  "to": ["user@example.com"],
  "cc": ["manager@example.com"],
  "subject": "Project update",
  "body": "Hi team,\n\nHere is the latest update...",
  "bodyType": "text"
}

Append to a Google Doc

{
  "documentId": "1AbCdEf...",
  "content": "\n\n## Meeting Notes\n- Decision 1\n- Decision 2"
}

Optional: "tabId": "..." targets a specific tab; "ensureLeadingNewline": true prepends a newline.

Testing

# Unit tests
npm test

# Integration tests (opt-in, requires real Google account)
RUN_INTEGRATION_TESTS=1 npm run test:integration

Docker

docker build -t google-workspace-mcp .
docker run -it --env-file .env -v $(pwd)/tokens.json:/app/data/tokens.json google-workspace-mcp

Security Considerations

• Never commit .env or tokens.json — both are gitignored

• OAuth tokens are never exposed in MCP tool inputs or outputs

• Email bodies and document content are not logged

• Use human confirmation before high-impact email sends when appropriate

• For production, replace file-based token storage with a secret manager

Troubleshooting

License

MIT