Calendar AutoAuth

The Calendar AutoAuth MCP Server lets you manage Google Calendar events directly from your AI assistant by handling OAuth2 authentication and calendar operations. It supports creating, listing, updating, retrieving, and deleting events, with a streamlined authentication flow that launches a browser for you and stores credentials locally for reuse.

How to use

You connect to the Calendar AutoAuth MCP Server from your MCP client by configuring a local or remote server entry. Once configured, you can create events by providing a title, start and end times, and optional description and location. You can list upcoming or historical events within a time window, fetch details for a specific event by its ID, update event fields such as title, time, description, or location, and delete events when needed.

How to install

Prerequisites you need before installation: Node.js and npm (Node.js 14+ or later is recommended). You also need access to Google Cloud to create OAuth credentials for the Calendar API.

1. Install the MCP server via a package workflow using Smithery:

npx -y @smithery/cli install @gongrzhe/server-calendar-autoauth-mcp --client claude

Configure authentication in Google Cloud

Create a Google Cloud Project and enable the Google Calendar API. Then create OAuth 2.0 credentials as either a Desktop app or Web application. For Web applications, add the local redirect URI http://localhost:3000/oauth2callback and download the credentials JSON file. Rename it to gcp-oauth.keys.json for consistency.

Authenticate from the command line

You have two authentication approaches. Use Global Authentication for convenience, or Local Authentication for in-directory setup.

# Global Authentication (recommended)
# Place gcp-oauth.keys.json in your home directory's .calendar-mcp folder
mkdir -p ~/.calendar-mcp
mv gcp-oauth.keys.json ~/.calendar-mcp/

# Run authentication from anywhere
npx @gongrzhe/server-calendar-autoauth-mcp auth

# Local Authentication
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-calendar-autoauth-mcp auth

What happens during authentication

The process looks for gcp-oauth.keys.json in the current directory or in ~/.calendar-mcp/. If found locally, it’s copied to the global config. It then opens your browser to complete Google authentication and saves credentials to ~/.calendar-mcp/credentials.json.

Claude Desktop configuration

Configure your Claude Desktop MCP entry to point to the server using npx. This enables the Calendar MCP to be available under the name calendar.

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-calendar-autoauth-mcp"
      ]
    }
  }
}

Docker support

If you prefer Docker, you can authenticate and run the MCP server inside a container. The examples below show how to provide the path to your Google credentials and where to store credentials.

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-calendar:/calendar-server \
  -e CALENDAR_OAUTH_PATH=/gcp-oauth.keys.json \
  -e CALENDAR_CREDENTIALS_PATH=/calendar-server/credentials.json \
  -p 3000:3000 \
  mcp/calendar auth

Using in Docker (start command)

To run the MCP server in Docker as part of Claude Desktop setup, proxy the configuration through an entry similar to this.

{
  "mcpServers": {
    "calendar": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-calendar:/calendar-server",
        "-e",
        "CALENDAR_CREDENTIALS_PATH=/calendar-server/credentials.json",
        "mcp/calendar"
      ]
    }
  }
}

Usage examples

The server supports a range of calendar actions such as creating events, listing events within a time range, updating events, retrieving a single event, and deleting events. Use the MCP client to issue requests corresponding to these actions.

Security notes

OAuth credentials are stored securely in your local environment (~/.calendar-mcp/). The server uses offline access to maintain persistent authentication. Do not share or commit credentials. Regularly review and revoke unused access in your Google Account settings. Credentials are stored globally but are accessible only to the current user.

Troubleshooting

OAuth keys not found: Ensure gcp-oauth.keys.json is either in your current directory or in ~/.calendar-mcp/. Check file permissions.

Invalid credentials format: Ensure the OAuth keys file contains valid web or installed credentials and that the redirect URI is configured correctly for web apps.

Port conflicts: If port 3000 is already in use, free the port before running authentication.

Notes

Global credentials are stored in ~/.calendar-mcp/credentials.json and can be reused across directories. Both Desktop and Web application credentials are supported.

Contributing

Contributions are welcome. Submit a Pull Request with your changes.

License

ISC License.

Author

gongrzhe

Support

For issues or questions, file an issue on the project's hosting platform.

Available tools

createEvent

Create a calendar event with title, start/end times, description, and location.

getEvent

Retrieve details for a specific event by its event ID.

updateEvent

Update fields of an existing event such as title, time, description, or location.

deleteEvent

Delete an event using its event ID.

listEvents

List events within a specified time range.

authenticateOAuth

Perform OAuth2 authentication with automatic browser launch and credential storage.