bn-google-workspace-mcp-server

v0.0.4

Published

11 days ago

Stateless MCP Server for Google Workspace APIs

0High
0Medium
0Low

gongrzhe

mcp google-workspace gmail drive calendar docs sheets slides tasks forms chat stateless

Google Workspace MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Workspace services including Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, and Chat with OAuth2 authentication.

Features

Gmail Operations: List labels, search messages, send emails, get message content
Google Drive: File management, content access, and file creation
Google Calendar: Event management and calendar operations
Google Docs: Document creation and content access
Google Sheets: Spreadsheet operations, data reading and creation
Google Slides: Presentation management and creation
Google Forms: Form creation and management
Google Tasks: Task list and task management
Google Chat: Space management and messaging
OAuth2 Authentication: Secure access via Google Access Tokens
Stateless Architecture: Each request is independent with Bearer token authentication
TypeScript Implementation: Built with TypeScript for type safety and maintainability

Quick Start

Installation

# Install dependencies
pnpm install

# Build the TypeScript project
pnpm run build

# Start the server
pnpm start

# Or run in development mode with auto-reload
pnpm run dev

# Run with debug logging enabled
pnpm run dev:debug

Docker

# Build the Docker image
docker build -t google-workspace-mcp .

# Run the container
docker run -p 30000:30000 google-workspace-mcp

The server provides these endpoints:

POST /mcp - Main MCP endpoint for tool execution
GET /health - Health check endpoint

Authentication

All requests require a Google Access Token via Authorization header:

Authorization: Bearer ya29.your-google-access-token

Set up Google OAuth2 and obtain access tokens with appropriate scopes.

Tools

The server provides 25 tools for comprehensive Google Workspace API access. Each tool requires Authorization: Bearer <token> header.

Gmail Tools

1. gmail_list_labels

List all Gmail labels.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "gmail_list_labels",
      "arguments": {}
    }
  }'

2. gmail_search_messages

Search Gmail messages.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "gmail_search_messages",
      "arguments": {
        "query": "is:unread from:[email protected]",
        "maxResults": 20
      }
    }
  }'

3. gmail_get_message_content

Get detailed information about a specific Gmail message.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "gmail_get_message_content",
      "arguments": {
        "messageId": "1234567890abcdef"
      }
    }
  }'

4. gmail_send_message

Send a Gmail message.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "gmail_send_message",
      "arguments": {
        "to": "[email protected]",
        "subject": "Hello from Google Workspace MCP",
        "body": "This email was sent via the MCP server!"
      }
    }
  }'

Google Drive Tools

5. drive_list_files

List Google Drive files.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "tools/call",
    "params": {
      "name": "drive_list_files",
      "arguments": {
        "query": "project",
        "maxResults": 15
      }
    }
  }'

6. drive_get_file_content

Get Google Drive file content.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "6",
    "method": "tools/call",
    "params": {
      "name": "drive_get_file_content",
      "arguments": {
        "fileId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

7. drive_create_file

Create a Google Drive file.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "7",
    "method": "tools/call",
    "params": {
      "name": "drive_create_file",
      "arguments": {
        "name": "my-document.txt",
        "content": "Hello, this is my new document content!",
        "parentFolderId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

Google Calendar Tools

8. calendar_list_events

List Google Calendar events.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "8",
    "method": "tools/call",
    "params": {
      "name": "calendar_list_events",
      "arguments": {
        "maxResults": 25
      }
    }
  }'

9. calendar_list_calendars

List Google Calendars.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "9",
    "method": "tools/call",
    "params": {
      "name": "calendar_list_calendars",
      "arguments": {}
    }
  }'

10. calendar_create_event

Create a Google Calendar event.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "10",
    "method": "tools/call",
    "params": {
      "name": "calendar_create_event",
      "arguments": {
        "summary": "Team Meeting",
        "startTime": "2024-01-15T10:00:00-08:00",
        "endTime": "2024-01-15T11:00:00-08:00"
      }
    }
  }'

Google Docs Tools

11. docs_get_document

Get Google Docs document.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "11",
    "method": "tools/call",
    "params": {
      "name": "docs_get_document",
      "arguments": {
        "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

12. docs_create_document

Create a Google Docs document.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "12",
    "method": "tools/call",
    "params": {
      "name": "docs_create_document",
      "arguments": {
        "title": "My New Document",
        "content": "This is the initial content of my document."
      }
    }
  }'

Google Sheets Tools

13. sheets_get_spreadsheet

Get Google Sheets spreadsheet.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "13",
    "method": "tools/call",
    "params": {
      "name": "sheets_get_spreadsheet",
      "arguments": {
        "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

14. sheets_read_values

Read values from Google Sheets.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "14",
    "method": "tools/call",
    "params": {
      "name": "sheets_read_values",
      "arguments": {
        "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
        "range": "A1:D10"
      }
    }
  }'

15. sheets_create_spreadsheet

Create a Google Sheets spreadsheet.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "15",
    "method": "tools/call",
    "params": {
      "name": "sheets_create_spreadsheet",
      "arguments": {
        "title": "My New Spreadsheet"
      }
    }
  }'

Google Slides Tools

16. slides_get_presentation

Get Google Slides presentation.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "16",
    "method": "tools/call",
    "params": {
      "name": "slides_get_presentation",
      "arguments": {
        "presentationId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

17. slides_create_presentation

Create a Google Slides presentation.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "17",
    "method": "tools/call",
    "params": {
      "name": "slides_create_presentation",
      "arguments": {
        "title": "My New Presentation"
      }
    }
  }'

Google Tasks Tools

18. tasks_list_task_lists

List Google Tasks task lists.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "18",
    "method": "tools/call",
    "params": {
      "name": "tasks_list_task_lists",
      "arguments": {}
    }
  }'

19. tasks_list_tasks

List tasks from a Google Tasks list.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "19",
    "method": "tools/call",
    "params": {
      "name": "tasks_list_tasks",
      "arguments": {
        "taskListId": "@default"
      }
    }
  }'

20. tasks_create_task

Create a task in Google Tasks.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "20",
    "method": "tools/call",
    "params": {
      "name": "tasks_create_task",
      "arguments": {
        "taskListId": "@default",
        "title": "Complete project documentation",
        "notes": "Review and finalize all documentation for the project"
      }
    }
  }'

Google Forms Tools

21. forms_create_form

Create a Google Form.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "21",
    "method": "tools/call",
    "params": {
      "name": "forms_create_form",
      "arguments": {
        "title": "Customer Feedback Survey"
      }
    }
  }'

22. forms_get_form

Get Google Form information.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "22",
    "method": "tools/call",
    "params": {
      "name": "forms_get_form",
      "arguments": {
        "formId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
      }
    }
  }'

Google Chat Tools

23. chat_list_spaces

List Google Chat spaces.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "23",
    "method": "tools/call",
    "params": {
      "name": "chat_list_spaces",
      "arguments": {}
    }
  }'

24. chat_send_message

Send a message to Google Chat.

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "24",
    "method": "tools/call",
    "params": {
      "name": "chat_send_message",
      "arguments": {
        "spaceName": "spaces/AAAAxxxxxxx",
        "text": "Hello from the Google Workspace MCP Server!"
      }
    }
  }'

List Available Tools

Get the complete list of available tools:

curl -X POST http://localhost:30000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ya29.your-google-access-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'

Project Structure

google-workspace/
├── package.json          # NPM configuration
├── tsconfig.json         # TypeScript configuration
├── Dockerfile            # Container configuration
├── tools.json            # Tool definitions for MCP
├── nodemon.json          # Dev mode configuration
├── src/
│   ├── index.ts          # Main server entry point
│   ├── schemas.ts        # Zod schemas for all tools
│   ├── tool-registry.ts  # Tool registration system
│   ├── tool-loader.ts    # Tool definitions loader
│   ├── debug-middleware.ts # Debug logging
│   ├── types.ts          # TypeScript interfaces
│   ├── helpers.ts        # Utility functions
│   ├── google-api-client.ts # Google API service factories
│   └── tools/
│       ├── index.ts      # Tool exports
│       ├── gmail.ts      # Gmail tools
│       ├── drive.ts      # Drive tools
│       ├── calendar.ts   # Calendar tools
│       ├── docs.ts       # Docs tools
│       ├── sheets.ts     # Sheets tools
│       ├── slides.ts     # Slides tools
│       ├── tasks.ts      # Tasks tools
│       ├── forms.ts      # Forms tools
│       └── chat.ts       # Chat tools
└── dist/                 # Compiled JavaScript

Authentication Setup

Create Google Cloud Project:
- Go to Google Cloud Console
- Create a new project or select existing
- Enable required APIs (Gmail, Drive, Calendar, etc.)
Set up OAuth2:
- Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
- Configure OAuth consent screen
- Download client configuration

Required Scopes:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/presentations
https://www.googleapis.com/auth/tasks
https://www.googleapis.com/auth/forms.body
https://www.googleapis.com/auth/chat.spaces

Get Access Token:
- Use Google OAuth2 flow to obtain access tokens
- Pass tokens via Authorization: Bearer header

Configuration

Environment Variables

# Server Configuration
PORT=30000           # Server port (default: 30000)
DEBUG=true           # Enable debug logging

# Tool Configuration
TOOLS_CONFIG_PATH=./tools.json  # Custom path to tools.json

Development

Run in Development Mode

# Auto-reload on file changes
pnpm run dev

# With debug logging enabled
pnpm run dev:debug

Build for Production

pnpm run build
pnpm start

Error Handling

The server provides detailed error messages for common issues:

401: Invalid or expired Google access token
403: Insufficient permissions or missing scopes
404: Resource not found (document, file, etc.)
429: Rate limit exceeded
500: Internal server errors

License

This MCP server is licensed under the MIT License.