README - mcp-google by 199-mcp

MCP Google Workspace

The ONLY comprehensive MCP server for Google Workspace that enables Claude, Cursor, Windsurf and other AI systems to fully manage Google Calendar, Contacts, AND Gmail - read, create, update, delete, and organize across all three services!

Complete Google Workspace integration for Claude Desktop and other AI agents using the Model Context Protocol (MCP). This server provides comprehensive management capabilities for Calendar, Contacts, and Gmail with OAuth2 authentication.

Why This MCP Server?

Other calendar MCP servers only provide read-only access. This is the only MCP server that gives AI systems like Claude, Cursor, and Windsurf the ability to:

Calendar Management

✅ Create new calendar events
✅ Update existing events (including recurring events)
✅ Delete events
✅ Manage multiple calendars
✅ Check availability across calendars

Contact Management

✅ List and search contacts
✅ Create new contacts with full details
✅ Update existing contacts
✅ Delete contacts
✅ Manage contact details (emails, phones, addresses, organizations)

Gmail Management (NEW!)

✅ Search and list emails with powerful queries
✅ Read full email content with attachments
✅ Send new emails and replies
✅ Organize with labels and folders
✅ Update email status (read/unread, starred, important)
✅ Create and manage drafts
✅ Batch operations for bulk email management

Features

Calendar Features

Multi-Calendar Support: List events from multiple calendars simultaneously
Event Management: Create, update (including notifications), delete, and search calendar events
Recurring Events: Advanced modification scopes for recurring events (single instance, all instances, or future instances only)
Calendar Management: List calendars and their properties
Free/Busy Queries: Check availability across calendars

Contact Features

Contact Search: Search contacts by name, email, or other criteria
Full Contact Details: Manage names, emails, phone numbers, addresses, organizations, and notes
Batch Operations: List contacts with pagination support
Field Selection: Choose which contact fields to retrieve for optimized responses

Gmail Features (NEW!)

Advanced Search: Use Gmail's powerful search operators
Email Management: Read, send, reply, forward, and delete emails
Label Organization: Create and manage labels/folders
Draft Management: Create, update, and send drafts
Batch Operations: Update multiple emails at once
Thread Support: Handle email conversations
Attachment Info: View attachment details (names, sizes, types)

Authentication

OAuth2 Authentication: Secure authentication with automatic token refresh
Unified Permissions: Single authentication flow for Calendar, Contacts, and Gmail access

Installation

Via npx (Recommended)

npx mcp-google

Via npm

npm install -g mcp-google

Setup

1. Create Google OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Enable these APIs:
- Google Calendar API
- Google People API
Configure OAuth consent screen:
- Go to "APIs & Services" > "OAuth consent screen"
- Choose "External" user type
- Fill in required fields (app name, support email, etc.)
- Add your email as a test user (required while in test mode)
Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as the application type
- Name your OAuth client (e.g., "MCP Calendar Client")
- Download the credentials JSON file

2. Configure Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Direct Environment Variables (Simplest - No JSON file needed!)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Option B: Use Downloaded Google Credentials File

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/downloaded/credentials.json"
      }
    }
  }
}

Just use the file path where you saved the JSON file downloaded from Google Cloud Console.

3. Authenticate

Restart Claude Desktop
The MCP server will open a browser window for authentication
Log in with your Google account and grant Calendar, Contacts, AND Gmail permissions
Tokens will be saved securely for future use

Note: If upgrading from a previous version, you'll need to re-authenticate to grant the new Gmail permissions.

Environment Variables

GOOGLE_OAUTH_CREDENTIALS: Path to OAuth credentials JSON file
GOOGLE_CALENDAR_MCP_TOKEN_PATH: Custom path for token storage (optional)
NODE_ENV: Set to "production" for production use

Available Tools

Calendar Tools

list-calendars

List all accessible calendars with their properties.

list-events

List events from one or more calendars with filtering options.

create-event

Create a new calendar event with support for:

Single or recurring events
Attendees and notifications
Custom colors
Time zones

update-event

Update existing events including:

Modifying single instances of recurring events
Changing event details
Managing attendees

delete-event

Delete events from calendars.

search-events

Search for events across calendars using text queries.

get-freebusy

Query free/busy information across multiple calendars.

list-colors

List available calendar event colors.

Contact Tools

list-contacts

List and search contacts with pagination support.

get-contact

Get detailed information about a specific contact.

create-contact

Create new contacts with:

Names and nicknames
Multiple email addresses
Phone numbers
Physical addresses
Organizations and job titles
Notes and biographies

update-contact

Update existing contact information with field-specific updates.

delete-contact

Delete contacts from Google Contacts.

Gmail Tools (NEW!)

list-emails

Search and list emails with powerful Gmail queries.

get-email

Read full email content including body and attachments.

send-email

Send new emails or replies with HTML support.

update-email

Modify email properties (labels, read status, star, archive).

delete-email

Move emails to trash or permanently delete.

create-draft

Create email drafts for later editing.

update-draft

Edit existing email drafts.

send-draft

Send a saved draft.

list-labels

List all Gmail labels/folders.

create-label

Create new labels for organizing emails.

update-label

Modify label properties and colors.

delete-label

Remove labels from Gmail.

batch-update-emails

Perform bulk operations on multiple emails.

Example Usage

Calendar Examples

Check availability

What times am I free tomorrow between 9am and 5pm?

Create an event

Create a meeting called "Team Standup" tomorrow at 10am for 30 minutes

Search for events

Find all events this week that mention "project review"

Update recurring events

Change all future instances of my weekly team meeting to 2pm

Contact Examples

List contacts

Show me all my contacts with email addresses

Create a contact

Create a contact for John Doe, email: john@example.com, phone: 555-1234

Search contacts

Find contacts who work at Google

Update contact

Update Jane Smith's phone number to 555-5678

Gmail Examples

Search emails

Show me all unread emails from this week

Send email

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 2pm"

Organize inbox

Mark all newsletters as read and archive them

Manage labels

Create a label called "Important Projects" and apply it to all emails from my manager

Batch operations

Move all emails older than 30 days to trash

Troubleshooting

Authentication Issues

Ensure redirect URI matches exactly: http://localhost:3000/oauth2callback
Check that both Calendar API and People API are enabled in Google Cloud Console
Verify OAuth credentials are for a "Desktop app" type
If upgrading from calendar-only, re-run authentication to grant contacts permissions

Token Expiration

Tokens are automatically refreshed
If issues persist, delete the token file and re-authenticate

Permission Errors

Ensure you've granted all requested Calendar, Contacts, and Gmail permissions
Check that the Google account has access to the resources you're trying to access
Ensure all required APIs are enabled in your Google Cloud project:
- Google Calendar API
- Google People API
- Gmail API

Security

OAuth tokens are stored with restricted permissions (0600)
Client secrets should never be committed to version control
Use environment variables for sensitive configuration

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Team

Developed by Boris Djordjevic and the 199 Longevity team.

Built on top of the original google-calendar-mcp by nspady.

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Changelog

v1.1.3

Fixed timezone validation to support milliseconds in ISO timestamps
Now compatible with JavaScript's Date.toISOString() format (e.g., 2024-01-01T00:00:00.000Z)
Improved datetime validation regex to handle both formats with and without milliseconds

v1.1.2

Improved authentication flow with clear, informative landing page
Users now see exactly what permissions Claude will have before connecting
Professional UI that clearly identifies this as Google Calendar authentication
Added security note that credentials are never stored

v1.1.1

Enhanced documentation to highlight unique full calendar management capabilities
Added "Why This MCP Server?" section emphasizing create/update/delete features
Updated package description and keywords for better discoverability

v1.1.0

Simplified setup: Added support for direct environment variables (no JSON file needed!)
Users can now use GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET directly in Claude config
Updated README with clearer Desktop app OAuth setup instructions
Removed unnecessary redirect URI configuration steps

v1.0.1

Added automatic retry logic for network errors
Improved error handling for socket hang-up issues
Silent recovery when events are created despite connection errors

v1.0.0

Initial release with enhanced OAuth2 authentication
Comprehensive calendar management tools
Multi-calendar support
Free/busy queries