Setup

Connect cocal to your AI

cocal is a bridge between your Google Calendars and the AI assistant you already use. Pick your client below — setup takes about a minute.

MCP server URL

https://mcp.cocal.io

Paste this URL into your MCP client's connector settings. cocal uses OAuth, so there's no token or secret to copy.

Claude Desktop

macOS and Windows app. Native MCP support.

  1. Open Settings → Connectors.
  2. Click Add connector. Name it cocal and paste the URL https://mcp.cocal.io.
  3. Save. Claude opens a browser window to cocal.io — sign in if you haven't already, then approve the connection.
  4. Start a new chat and try the prompt below.

Try first

What's on my calendar today?

Under the hood: Claude hits mcp.cocal.io/authorize, cocal.io handles Google sign-in, and the MCP token is stored locally. Tokens are ephemeral — Railway redeploys invalidate active sessions and you may need to reconnect.

claude.ai

The web app at claude.ai. Custom connectors on eligible plans.

  1. In claude.ai, open Settings → Connectors. Organization admins may need to allow custom connectors first.
  2. Click Add custom connector. Paste the URL https://mcp.cocal.io. Leave auth-header fields blank — OAuth handles itself.
  3. Save. A popup opens to cocal.io for sign-in and approval.
  4. In a new conversation, enable the cocal connector from the connector tray beside the chat input.

Try first

Find me a 45-min slot on Wednesday across all my calendars.

Custom connectors require an eligible Claude plan (Pro, Team, or Enterprise). Check your plan before starting if you don't see the connector settings.

Claude Code

The Claude CLI. One command to add cocal.

  1. Install Claude Code if you haven't: brew install anthropic/tap/claude, or follow the instructions at claude.com/claude-code.
  2. In any terminal, run:
    claude mcp add --transport http cocal https://mcp.cocal.io
  3. Run claudeto start a session. On the first tool call, Claude Code opens a browser to cocal.io — sign in and approve.
  4. Try the prompt below.

Try first

List my events next Monday and flag any conflicts with my personal calendar.

To scope cocal to a single project, add --scope project. Remove with claude mcp remove cocal.

What cocal asks Google for

cocal requests the minimum scopes needed for calendar management, so Google's consent screen stays short:

cocal does not request the full calendar scope or calendar.acls(calendar sharing). Features that need more permission will prompt you for only that extra scope, when you use them — no up-front surprises.

Ready to connect?

You'll sign in to cocal with Google, then link one or more Google Calendar accounts. cocal asks for calendar permission once per account you connect.

Get started with Google