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 OAUTH_SETUP.md 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 TOOLS.md 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 docs/TROUBLESHOOTING.md 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

• Issues
• Documentation
• MCP Specification

Roadmap

Potential future additions (not committed):

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