io.github.danielsousaoliveira/cal-auto-python

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:

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/mcp.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"
      }
    }
  }
}

Generic (any stdio-capable MCP client)

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

To poke at the server without a client, point the MCP Inspector at it:

$ npx @modelcontextprotocol/inspector cal-auto-python server

Web-based clients, or anyone wanting to run the server on one machine and talk to it from another, can't launch a stdio child process. For them, run the server over HTTP instead:

$ cal-auto-python server --transport http --host 127.0.0.1 --port 8000

HTTP mode is single-user and intended for local use only. The server reads one person's stored Google authorisation from disk and has no notion of separate users; it adds no authorisation of its own on top of the HTTP endpoint. Exposing it on a shared or public network would hand everyone who can reach it access to that one calendar, so only bind it to 127.0.0.1 or a private, trusted network.

Prerequisites

• A GitHub personal access token with read access to the Projects V2 board you want to schedule from: a classic token with the read:project scope (plus repo if the board tracks items in private repositories), or a fine-grained token granted read access to Projects. Set it as GITHUB_TOKEN.
• The board's Projects V2 node ID, e.g. PVT_xxxxxxxxxx. Find it by querying the GitHub GraphQL API for the project, or from its URL and the Projects API docs. Set it as GITHUB_PROJECT_ID.
• A Google OAuth client (Desktop app type) as described in One-off authorisation above.

Capabilities

Two prompts wrap the common workflows, so they show up as one-click starting points in clients that support them (slash commands in Claude Code and Claude Desktop, for instance). Both take optional start_date and end_date (YYYY-MM-DD) and default to the next seven days.

The CLI exposes the same scheduling logic directly:

$ cal-auto-python sync --start 2026-08-17 --end 2026-08-21 --apply

sync previews by default; pass --apply to create events and tasks, and --start/--end (YYYY-MM-DD) or --working-day-start/--working-day-end (HH:MM) to override the default range (today plus the next two days) and working hours.

Configuration

Every variable below is optional except GITHUB_TOKEN, GITHUB_PROJECT_ID, and CAL_AUTO_TIMEZONE, which has no default and must be set.

Configuration is read from the process environment. MCP clients pass these in the env block of their server config. For CLI use you can either export them, or copy .env.example to .env and point the command at it explicitly:

$ cal-auto-python sync --env-file .env

--env-file loads the given file (and only when passed — nothing is read from the working directory automatically). Only CAL_AUTO_* and GITHUB_* keys are applied; anything else in the file is ignored with a warning. Variables already set in the environment win over the file.

Troubleshooting

Authorisation error / "Google account has not been authorised" Run cal-auto-python authorize again. This also fixes an expired authorisation that couldn't be refreshed automatically (Google revokes a refresh token after long inactivity or if access is revoked from your Google Account settings) — the server reports this explicitly rather than failing silently.

Events show up at unexpected times Check CAL_AUTO_TIMEZONE. It must be a valid IANA name (e.g. Europe/Lisbon, not CET or a UTC offset) and must match the timezone you actually work in — the scheduler places events using this value, not your system timezone.

list_tracker_items or sync_backlog return nothing, even though the board has cards CAL_AUTO_SCHEDULABLE_STATUSES (default Backlog) must match your board's status column names exactly, including case. Open the board and copy the status name verbatim, or pass an explicit statuses argument to list_tracker_items to confirm what the board actually reports.

Roadmap

[x] Retrieve project data from github \ [x] Add events and tasks to google calendar \ [x] Schedule based on priority \ [x] Fix duplicated events and tasks \ [x] Replace the hardcoded entry point with a real CLI \ [x] Run as an MCP server (cal-auto-python server) \ [x] Optimize event distribution \ [x] Update or move an event when the plan changes

Contributing

Adding another task tracker or calendar backend? See docs/ARCHITECTURE.md for the layers and a walkthrough, and CONTRIBUTING.md for how to run the tests, linter, and type checker.

References

Google Calendar API \ Github Projects API