The ONLY comprehensive MCP server for Google Workspace - Calendar, Contacts, and Gmail management in Claude, Cursor, Windsurf
npm install mcp-googleThe 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.
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:
``bash`
npx mcp-google
`bash`
npm install -g mcp-google
1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable these APIs:
- Google Calendar API
- Google People API
4. 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)
5. 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
Add this to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
Windows:
#### Option A: Direct Environment Variables (Simplest - No JSON file needed!)
`json`
{
"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
`json`
{
"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.
1. Restart Claude Desktop
2. The MCP server will open a browser window for authentication
3. Log in with your Google account and grant Calendar, Contacts, AND Gmail permissions
4. 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.
- GOOGLE_OAUTH_CREDENTIALS: Path to OAuth credentials JSON fileGOOGLE_CALENDAR_MCP_TOKEN_PATH
- : Custom path for token storage (optional)NODE_ENV
- : Set to "production" for production use
#### 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.
#### 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.
#### 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.
#### 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
#### 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
#### 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
- 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$3
- Tokens are automatically refreshed
- If issues persist, delete the token file and re-authenticate$3
- 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 APISecurity
- OAuth tokens are stored with restricted permissions (0600)
- Client secrets should never be committed to version control
- Use environment variables for sensitive configuration
Development
`bash
Install dependencies
npm installBuild
npm run buildRun 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
$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$3
- 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$3
- 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$3
- 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