Google Calendar MCP Server is a Model Context Protocol server that provides Google Calendar integration for AI assistants like Claude. It allows assistants to manage calendar events, check availability across multiple calendars, and intelligently interpret scheduling requests with natural language understanding.
Before installation, you'll need:
https://www.googleapis.com/auth/calendar.events
and https://www.googleapis.com/auth/calendar
Add to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": ["@cocal/google-calendar-mcp"],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
⚠️ Important Note: When using npx, you must specify the credentials file path using the GOOGLE_OAUTH_CREDENTIALS
environment variable.
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
Then add to Claude Desktop config using the local path or by specifying the path with the GOOGLE_OAUTH_CREDENTIALS
environment variable.
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up
If you're in test mode (default), tokens expire after 7 days. To re-authenticate:
For npx users:
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth
For local installation:
npm run auth
To avoid weekly re-authentication, publish your app to production mode:
Here are some examples of what you can do with the Google Calendar MCP:
Cross-calendar availability:
Please provide availability looking at both my personal and work calendar for this upcoming week.
I am looking for a good time to meet with someone in London for 1 hr.
Add events from screenshots and images:
Add this event to my calendar based on the attached screenshot.
Supported image formats: PNG, JPEG, GIF
Calendar analysis:
What events do I have coming up this week that aren't part of my usual routine?
Check attendance:
Which events tomorrow have attendees who have not accepted the invitation?
Auto coordinate events:
Here's some available that was provided to me by someone. {available times}
Take a look at the times provided and let me know which ones are open on my calendar.
Tool | Description |
---|---|
list-calendars |
List all available calendars |
list-events |
List events with date filtering |
search-events |
Search events by text query |
create-event |
Create new calendar events |
update-event |
Update existing events |
delete-event |
Delete events |
get-freebusy |
Check availability across calendars, including external calendars |
list-colors |
List available event colors |
Environment Variables:
GOOGLE_OAUTH_CREDENTIALS
- Path to OAuth credentials fileGOOGLE_CALENDAR_MCP_TOKEN_PATH
- Custom token storage location (optional)Claude Desktop Config Location:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
OAuth Credentials File Not Found:
GOOGLE_OAUTH_CREDENTIALS
Authentication Errors:
"Something went wrong" screen during browser authentication
For re-authentication or troubleshooting:
# For npx installations
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth
# For local installations
npm run auth
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "google-calendar" '{"command":"npx","args":["@cocal/google-calendar-mcp"],"env":{"GOOGLE_OAUTH_CREDENTIALS":"/path/to/your/gcp-oauth.keys.json"}}'
See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json
file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json
file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json
file will be opened and you can add your server like this:
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
To add an MCP server to a project you can create a new .cursor/mcp.json
file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.config/Claude/claude_desktop_config.json
2. Add this to your configuration file:
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
3. Restart Claude Desktop for the changes to take effect