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.

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 Desktop / Claude Code

Add to claude_desktop_config.json (Desktop) or run claude mcp add (Claude Code), or paste this into either client's MCP settings:

{
  "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"
  }
}

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

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. Copy .env.example to .env if you use an environment loader.

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