google-mcp

dslh/google-mcp

3.2

If you are the rightful owner of google-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A secure and focused Model Context Protocol (MCP) server for integrating Google Drive, Docs, and Calendar with AI assistants like Claude.

Tools
20
Resources
0
Prompts
0

Google MCP Server

A focused, secure Model Context Protocol (MCP) server providing Google Drive, Docs, and Calendar integration for AI assistants like Claude.

Features

  • Minimal & Focused: 20 carefully chosen tools covering essential Google services operations
  • Secure by Design: OAuth 2.0 with encrypted token storage and automatic refresh
  • Production Ready: Comprehensive error handling, validation, and logging
  • Well-Documented: Clear tool descriptions and detailed setup guides

Supported Services

  • Google Drive (7 tools): List, read, create, update files and folders, share files
  • Google Docs (6 tools): Read, create, modify documents, manage structure
  • Google Calendar (7 tools): List, create, update, delete events, find free time

Quick Start

1. Installation

npm install
npm run build

2. OAuth Setup

  1. Create a project in Google Cloud Console
  2. Enable the Drive, Docs, and Calendar APIs
  3. Create OAuth 2.0 credentials
  4. Copy .env.example to .env and fill in your credentials

See for detailed instructions.

3. Authenticate

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Run authentication flow
npm start -- --auth

This will open a browser window for you to authorize the application. Once complete, your credentials will be securely stored.

4. Use with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google": {
      "command": "node",
      "args": ["/path/to/google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Restart Claude Desktop, and the Google tools will be available.

Available Tools

Google Drive

  • drive_list_files - List and search files
  • drive_get_file_metadata - Get detailed file information
  • drive_read_file - Read file contents
  • drive_create_file - Create new file
  • drive_update_file - Update existing file
  • drive_create_folder - Create folder
  • drive_share_file - Share file with user

Google Docs

  • docs_read_document - Read document contents
  • docs_create_document - Create new document
  • docs_append_content - Append to document
  • docs_replace_content - Find and replace text
  • docs_insert_content - Insert at position
  • docs_get_structure - Get document outline

Google Calendar

  • calendar_list_events - List events in date range
  • calendar_get_event - Get event details
  • calendar_create_event - Create new event
  • calendar_update_event - Update event
  • calendar_delete_event - Delete event
  • calendar_find_free_time - Find available slots
  • calendar_list_calendars - List all calendars

See for detailed tool documentation with examples.

CLI Usage

# Start MCP server (for use with Claude Desktop)
npm start

# Authenticate with Google
npm start -- --auth

# Revoke credentials
npm start -- --revoke

# Show help
npm start -- --help

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild)
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format code
npm run format

Configuration

Environment Variables

GOOGLE_CLIENT_ID=your_client_id          # Required
GOOGLE_CLIENT_SECRET=your_client_secret  # Required
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback  # Optional
TOKEN_STORAGE_PATH=~/.google-mcp/tokens.json  # Optional
LOG_LEVEL=info  # Optional: debug, info, warn, error

OAuth Scopes

The server requests these scopes:

  • https://www.googleapis.com/auth/drive - Full Drive access
  • https://www.googleapis.com/auth/documents - Docs read/write
  • https://www.googleapis.com/auth/calendar - Calendar read/write

Security

  • OAuth tokens are stored encrypted at ~/.google-mcp/tokens.json with file permissions 0600
  • Tokens are automatically refreshed before expiration
  • No user data is logged or transmitted except to Google APIs
  • Client secret should be kept secure and not committed to version control

Troubleshooting

"Not authenticated" error

Run npm start -- --auth to authenticate.

Token expired

The server automatically refreshes tokens. If you see auth errors, re-run authentication.

Google API errors

Check that:

  1. APIs are enabled in Google Cloud Console
  2. OAuth credentials are correct
  3. Redirect URI matches your configuration

See for more help.

Architecture

src/
├── index.ts           # MCP server entry point
├── auth/              # OAuth 2.0 implementation
├── tools/             # Tool implementations
│   ├── drive/
│   ├── docs/
│   └── calendar/
├── types/             # TypeScript type definitions
└── utils/             # Error handling, validation, logging

Why This Server?

Existing Google MCP servers often:

  • Expose too many tools (overwhelming)
  • Mix multiple unrelated services (Gmail, Sheets, etc.)
  • Lack proper error handling
  • Are published by unknown third parties

This server focuses on:

  • Quality over quantity: 20 essential tools, not 100 mediocre ones
  • Security: Proper OAuth 2.0 with token encryption
  • Reliability: Comprehensive error handling and validation
  • Clarity: Well-documented, focused feature set

License

MIT

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure npm run lint and npm test pass
  5. Submit a pull request

Support

Roadmap

Potential future additions (not committed):

  • Gmail integration
  • Google Sheets support
  • Batch operations
  • Caching for performance
  • Web UI for OAuth flow