Automatic Calendar in Python

mcp-name: io.github.danielsousaoliveira/cal-auto-python

An MCP server that connects your GitHub Projects backlog to Google Calendar and Google Tasks. Point your assistant at it and ask it to show what's on your calendar, list your backlog, plan a week of work into your free time, or turn that plan into real events and to-dos.

A backlog board on the left becomes a scheduled week on the right, with each markdown checkbox carried across as its own to-do:

Before	After

Install

$ pip install cal-auto-python

This installs the cal-auto-python command, which runs both the CLI and the MCP server.

One-off authorisation

Before the server can read or write your calendar, you authorise it once against your Google account:

$ cal-auto-python authorize

This opens a browser window, asks you to sign in and grant calendar/tasks access, and stores the resulting token on disk (token.json in the config directory below). Do this before starting the server for the first time, and again any time authorisation expires — see Troubleshooting.

Authorisation needs a Google OAuth client:

1. In the Google Cloud Console, create a project (or reuse one) and enable the Google Calendar API and Google Tasks API.
2. Under APIs & Services → Credentials, create an OAuth client ID of type Desktop app, and download the resulting JSON.
3. Save it as credentials.json in the config directory (see Configuration for where that is and how to change it).

Connect it to your assistant

The server speaks MCP over stdio by default, which is what these clients expect. Every capability behaves the same regardless of client.

Claude Code

Register it in one command:

$ claude mcp add auto-calendar \
    -e GITHUB_TOKEN=your_github_token_here \
    -e GITHUB_PROJECT_ID=PVT_xxxxxxxxxx \
    -e CAL_AUTO_TIMEZONE=Europe/Lisbon \
    -- cal-auto-python server

Add -s user to make it available in every project instead of only the current one. To keep the token out of ~/.claude.json and out of the process list, put your settings in a file and pass that instead — note that the path must be absolute, since Claude Code starts the server from whichever directory you launch it in:

$ claude mcp add auto-calendar -- cal-auto-python server --env-file /absolute/path/to/.env

Then /mcp lists the server and its tools, and the prompts appear as /auto-calendar:plan-week and /auto-calendar:whats-scheduled. Use claude mcp list to check registration and claude mcp remove auto-calendar to undo it.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "auto-calendar": {
      "command": "cal-auto-python",
      "args": ["server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
        "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project (or the global `~/.cursor/

... View full README on GitHub