Skip to setup instructions
Julio M. Morales

Optional Notion Helper Tools

Notion-Google Calendar Sync

This optional helper tool connects the Calendar Database in my PhD Notion system with Google Calendar. It works alongside the existing Calendar Database. The PhD Notion system works without this integration. Use it when you want an optional connection between the Notion calendar and Google Calendar.

Supported events can be created, edited, rescheduled and explicitly deleted from either service. The integration keeps their mapped fields in step, records their identities locally and holds conflicting edits for review. It does not synchronize every kind of Google event or every Notion property. Read the supported behavior and limits before enabling it.

This is free, open-source software under the MIT license, using the official Notion and Google Calendar APIs. An API is the supported way for an application to read and change an account's data. You must configure your own accounts, credentials, database access and any required hosting. There is no hosted registration service, paid automation requirement or bundled access to my accounts.

Choose the guided desktop application for macOS or Windows, or run the same synchronization engine continuously on your own Raspberry Pi. The selected host must be powered on, awake, connected to the internet and running the application. Desktop startup at login starts after you sign in. It cannot sync while a laptop is asleep.

Privacy and data handling · Operator contact: juliomorales1823@gmail.com

Guide and implementation reviewed November 9, 2026. Release 0.2.3. Not affiliated with or endorsed by Google or Notion.

1. Choose a host and prepare accounts.

  • Notion: a workspace containing your Calendar Database, permission to edit its properties, and a workspace owner who can create an internal connection. On a managed workspace, its administrator may need to approve access.
  • Google: a Google account with owner or writer access to the calendar, plus permission to create a Google Cloud project and OAuth client. Read-only and free/busy calendar access are insufficient.
  • Desktop: a Mac with Intel or Apple Silicon, or Windows x64. The downloads include Python and the window toolkit; a separate Python installation is unnecessary. Windows 10/11 are the intended client targets; see the exact tested platforms.
  • Raspberry Pi alternative: Raspberry Pi OS or Debian Bookworm/Trixie, arm64 or armhf, with Python 3.11 or newer, administrator access, SSH (an encrypted remote connection) for installation and a browser on another computer for Google authorization. The installer checks the operating system and CPU architecture.
  • Network: outbound HTTPS access to Notion and Google. Normal polling needs no public address, port forwarding, domain, tunnel or paid hosting. Paid Notion database automations are not used.

Start with a dedicated test calendar and test Notion data source. Before connecting existing data, export or otherwise back up the participating provider data. Automatic application backups protect local synchronization state and settings; they are not a complete Notion or Google account backup.

Only one synchronizer may own a data-source/calendar pair. Stop an existing third-party sync, Pi service or other desktop worker for that pair before starting this one. Installing a desktop copy does not transfer another worker's saved links.

2. Prepare the Calendar Database.

Use the existing Calendar Database in the PhD Notion system. A database is a container; a data source is the particular table of entries and properties inside it. One database can contain several data sources. A calendar view is a way of displaying those entries, not a separate set of API permissions.

The names below are examples, not fixed requirements. Map the actual properties in your copy. For example, your existing title might be Task and your notes might be Note. Each mapped field needs its own distinct, writable property.

Field mapping. Scroll horizontally.
Field / server keyExample property and exact typeUse
Title · titleName · TitleRequired. Use the existing title column.
Date range · dateDate · DateRequired. One property holds start, optional end and whether times are enabled.
Google event identity · google_event_idNCS Event ID · Text, API rich_textRequired. Service-owned stable event ID. Keep it intact after linking.
Notes · descriptionNotes · TextOptional. Literal event description, not Notion page blocks.
Location · locationLocation · TextOptional.
Time zone · timezoneNCS Time Zone · TextOptional, recommended for exact daylight-saving behavior. Holds an IANA zone such as America/Denver.
Google event link · google_urlCalendar Link · URLOptional, service-owned clickable Google link. Google stores the Notion page identity in private metadata. A Notion source link is added when it does not replace another application's source; Google limits its visibility.
Recurrence · recurrenceRecurrence · TextOptional. Required to synchronize supported repeating series. See recurrence rules.
Participation · sync_enabledSync enabled · CheckboxOptional. If mapped, only checked, dated Notion entries participate. Check intended existing entries yourself.

No separate end-date, all-day checkbox or Notion-page-link column is required. Turn off time in the Date property for an all-day item. A timed entry with no end receives the configured duration, initially 60 minutes. Undated entries are skipped; clearing a linked date pauses that pair and retains its event.

Formula, Rollup, Relation, Status, People and other property types cannot stand in for the writable fields above. Page content, unmapped properties and existing third-party sync metadata remain outside the mapping. Text is called rich_text in the API, but this tool treats mapped text as literal text. Formatting inside a mapped title or Text value can be replaced when that field changes.

Optional category filtering uses an existing Select property and one exact option, for example Type = Research. Status and Multi-select are not supported category filters. Notion view filters do not limit this application's API scope. These types follow Notion's property reference.

3. Create a Notion connection and grant access.

  1. As a workspace owner, open the Notion Developer portal. Choose Build → Internal connections → Create, select the workspace and give the connection a recognizable name.
  2. In Configuration, enable Read content, Insert content and Update content. These allow reading entries, creating counterparts, changing mapped properties and moving supported pages to Trash. Comments and user email access are unnecessary.
  3. Copy the internal connection API token. This credential lets the application act as that connection. Keep it private. Desktop setup accepts it in a masked field and stores it in the operating system's credential store. The Pi uses the protected NOTION_TOKEN setting described below.
  4. Open Content access → Edit access, select the Calendar Database and save. Alternatively, open the database's ••• → Connections → Add connection and select the connection. Capability settings alone do not share the database. Sharing a parent can also expose descendants, so limit access to the intended data.
  5. In the database settings, open Manage data sources and use Copy data source ID for the intended source. Save that ID. The desktop can also discover it from the database's name, ID or URL and show each source for selection.

A database URL contains a database identifier; a ?v=… part refers to a view and is not the data source ID. The server's notion_data_source must hold the source ID. For API-based discovery, retrieve the database and select the appropriate entry in data_sources. This release sends Notion-Version: 2026-03-11 automatically.

Official references: create an internal connection and share content, capabilities, and database and data source IDs. An existing Notion MCP login is not a deployable token for this application.

4. Configure Google Cloud and OAuth.

OAuth is Google's browser-based permission flow. It gives this application a revocable grant without giving it your Google password. This build uses your own Desktop app OAuth client; it does not distribute the author's client credentials.

  1. Open Google Cloud Console, create or select a project, then open APIs & Services → Library. Enable Google Calendar API. Enabling only the Calendar MCP server/API is not this setup.
  2. Open Google Auth Platform. Complete Branding with an application name, support email and developer contact. Select an Audience. A personal Gmail account uses External; Internal is limited to eligible Google Workspace organizations.
  3. While the external app is in Testing, add your Google account to its test users. Under Data Access, configure the two scopes below. A scope is a named permission requested by the app.
  4. Under Clients → Create client, select Desktop app, name it and download the client JSON file, a structured configuration file. Do not use a Web application client or service-account key. Keep the JSON outside public repositories.
  5. For ongoing unattended use, finish the applicable consent settings and change the external app to In production, then authorize again. Calendar refresh tokens issued in Testing normally expire after seven days. Production removes that particular testing expiration; revocation, inactivity, security changes and administrator policy can still require reconnection.
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendarlist.readonly

The first permission reads and edits events; the second lists calendars so you can choose one. The OAuth grant can cover calendars accessible to your account. The application limits actual synchronization to the configured calendar. There is no requested scope limited to just one existing calendar.

Redirect address: the app automatically opens a local receiver at http://127.0.0.1:PORT/oauth/callback, choosing an unused port. This is a loopback address, meaning the same computer, not a publicly hosted page. A Desktop app client does not require a manually registered web redirect address. Leave Web application origins/redirect settings out of this setup. The browser and authorizing application must run on the same computer. The app uses random state and PKCE, a one-time proof that protects the authorization exchange.

Google's unverified-app warning can appear for a personal client. Personal-use verification exceptions may apply, but production status is not Google verification. Publicly distributing one OAuth client or using a managed account can require verification or administrator approval. Follow the policies for your account rather than treating the warning as a permission error to bypass.

Official references: enable APIs, consent settings, create Desktop app credentials, loopback authorization, refresh-token expiration, and verification requirements and exceptions.

5. Download and install release 0.2.3.

These permanent downloads are hosted on this website. They include no user credentials, private configuration or synchronization database. Keep the bundled third-party license notices with the application.

Also available: SHA-256 checksums, example server configuration, secret-file template, downloadable server setup notes, and release validation report. SHA-256 detects a changed or damaged download; it is not a trusted code-signing identity.

Check your download before opening it

A checksum is a file's digital fingerprint. Open the checksum list above, find the exact downloaded filename and compare its full SHA-256 value with the command's output. Uppercase and lowercase hexadecimal letters mean the same thing. If they differ, download the file again before running it. The examples below assume your browser saved the file in Downloads; use your actual folder and filename if different.

# macOS Terminal:
cd "$HOME/Downloads"
shasum -a 256 Notion-Calendar-Sync-0.2.3-macOS-universal2.dmg
# Windows PowerShell:
Set-Location "$env:USERPROFILE\Downloads"
(Get-FileHash ".\Notion-Calendar-Sync-0.2.3-Windows-x64.zip" -Algorithm SHA256).Hash

macOS

Open the disk image, drag Notion Calendar Sync.app to Applications, then open it. These builds are not Developer ID signed or notarized. If macOS blocks the first launch, review the app's source and checksum, then use its per-app Open Anyway option in System Settings → Privacy & Security, if available, and confirm the app name. Do not disable system-wide protections. Managed-device policy can prevent this approval. See Apple's instructions for opening downloaded apps. The universal image contains both CPU architectures.

Windows

Extract the entire portable ZIP to a local folder before opening Start Notion Calendar Sync.vbs. Do not run it from inside the ZIP. The included runtime needs no administrator privileges, separate Python or PATH changes. Install.vbs optionally copies it to your user's Programs directory and creates shortcuts. If Windows Script Host is disabled, use Start Notion Calendar Sync.cmd; it briefly opens a console while launching the window.

The native alternative contains Notion Calendar Sync.exe. Extract and retain its entire app folder before running it. These Windows builds are unsigned, so download protection or organization policy may block them. SmartScreen can offer an application-specific approval after you review its details; Smart App Control or managed policy may block unsigned apps without that option. Do not disable those protections. See Microsoft's explanation of app reputation and unsigned downloads. Native Windows ARM builds are not supplied.

Source

Extract the source ZIP to obtain notion-calendar-sync-0.2.3/. It includes the engine, desktop UI, tests, build instructions, scripts/install-pi.sh and deploy/. Personal deployment reports are intentionally omitted. Use the server instructions below rather than an account-specific configuration from another installation.

6. Connect accounts, select data and map desktop fields.

  1. Open the desktop app. Paste the Notion internal token into its masked field and connect. Select your downloaded Google Desktop client JSON, choose Authorize Google, and complete consent in the browser within five minutes. The system's default browser may have a different signed-in account from the browser where you configured Google Cloud. Sign in or choose the account that has access to your intended calendar. Return to the app when authorization finishes. The imported client, Notion token and Google access/refresh tokens are held in macOS Keychain or Windows Credential Manager.
  2. Search by the shared Notion database's name, or paste its database/data source ID or URL. Choose Find, then Use selected database / entered ID. When names repeat, compare the displayed identifiers. If the database has several sources, select the specific source with the Calendar Database's properties.
  3. Choose a writable Google calendar from the retrieved list. For the first test, choose your dedicated test calendar. To find a stable calendar ID manually, use Google Calendar → Settings and sharing → Integrate calendar → Calendar ID. An event's ID is a different identifier.
  4. Review each suggested field mapping. The dropdowns contain compatible properties from your actual schema. Required mappings are Title, Date range and Google event identity. Leave unwanted optional fields unselected. Separate start, end and all-day columns are not mapped.
  5. If needed, choose Create missing integration properties… and review the explicit confirmation. This action can add NCS Event ID, NCS Time Zone and Recurrence as Text, and Calendar Link as URL. It does not create the title, Date, Notes, Location or participation Checkbox for you. A same-name property with the wrong type must be corrected in Notion or replaced in your mapping.
  6. Optionally select a category Select property and its exact option. Optionally map a participation Checkbox. These filters limit Notion entries, not Google's authorization. Newly imported Google events receive the chosen category and participation value.
  7. Set the Default IANA time zone, missing-end duration, Poll interval and Full check interval. An IANA zone is a regional identifier such as Europe/London, which includes daylight-saving rules; an abbreviation such as EST is not an equivalent choice. Initial values are America/Denver, 60 minutes, 45 seconds and 900 seconds.

The desktop uses its UI settings, not environment variables or the Pi's TOML configuration file. TOML is a text format organized into named sections and settings, as shown below. The desktop supports one active data-source/calendar pair. Multiple mappings and additional conflict policies are available in the server configuration.

7. Preview and start safely.

  1. Choose Preview synchronization →. This reads current provider data without changing it. Review proposed creates, updates, stable-ID links, conflicts and unsupported or paused items.
  2. If both services already contain copies of the same items, check their stable links before approving any creates. Matching titles or dates do not prove identity. A saved pair, an exact Google event identity marker or the tool's private Google page marker can establish a link. A displayed event URL alone does not automatically establish one.
  3. For a new, empty test setup, confirm the preview contains only the intended test data. For historical data lacking preserved stable IDs, keep the app paused. This version has no historical-linking UI; use the explicit CLI linking procedure in a single server-owned setup before applying an initial import. Do not expect reconnecting the desktop to inherit another installation's SQLite links.
  4. Choose Approve this preview & start, then confirm. The app backs up local state/settings and rechecks current data. Changed or expired previews require a new review. Ordinary polling then runs continuously.

Pause, Resume, Reconnect accounts and Edit mapping are available on the dashboard. Changing a mapping requires a new preview. A scope change cannot silently reuse unrelated identities. Never delete the local state to clear an error or to force a fresh import.

8. Alternative: run the Raspberry Pi service.

Use this route instead of the desktop worker for the same pair. systemd, the Linux service manager, starts the worker at boot and restarts failures. SQLite is a local database that retains identities, pending operations, conflicts and deletion records across restarts.

Install the source on the Pi

For a headless Pi, these commands obtain and check the source ZIP without a graphical file manager. Use a new installation folder, and confirm that sha256sum reports OK before extracting:

sudo apt-get update
sudo apt-get install -y curl unzip
mkdir -p "$HOME/ncs-install-0.2.3"
cd "$HOME/ncs-install-0.2.3"
curl --fail --location --output Notion-Calendar-Sync-0.2.3-Source.zip \
  https://juliom1823.github.io/notion-calendar-sync/downloads/Notion-Calendar-Sync-0.2.3-Source.zip
curl --fail --location --output Notion-Calendar-Sync-0.2.3-Source.zip.sha256 \
  https://juliom1823.github.io/notion-calendar-sync/downloads/Notion-Calendar-Sync-0.2.3-Source.zip.sha256
sha256sum --check Notion-Calendar-Sync-0.2.3-Source.zip.sha256
unzip Notion-Calendar-Sync-0.2.3-Source.zip

Download and extract the source ZIP on the Pi, or copy the extracted folder there over SSH. From the directory containing the extracted notion-calendar-sync-0.2.3 folder, run:

cd notion-calendar-sync-0.2.3
cat /etc/os-release
dpkg --print-architecture
python3 --version
sudo sh scripts/install-pi.sh
sudoedit /etc/ncs/config.toml
sudoedit /etc/ncs/secrets.env

The installer accepts Bookworm/Trixie and arm64/armhf. It installs the distribution's Python/venv tools, time-zone data, CA certificates and SQLite, creates a dedicated ncs service account, installs code in /opt/ncs/app and a virtual environment in /opt/ncs/venv. It leaves synchronization disabled and preserves existing configuration on upgrades. The engine has no third-party Python runtime dependencies.

Set the exact configuration

Replace the placeholders and example property names below. All keys are implemented by this release. Paths here are the installer's Pi paths. In other installations, relative paths resolve against the TOML file's directory. Omit optional property keys when unused; TOML has no null value.

[service]
state_path = "/var/lib/ncs/sync.sqlite3"
google_token_path = "/var/lib/ncs/google-token.json"
google_client_path = "/etc/ncs/google-client.json"
notion_token_env = "NOTION_TOKEN"
log_level = "INFO"
public_url = ""

[[mappings]]
name = "calendar"
notion_data_source = "YOUR_DATA_SOURCE_UUID"
google_calendar = "YOUR_CALENDAR_ID"
timezone = "America/Denver"
poll_seconds = 45
reconcile_seconds = 900
notion_incremental = false
default_duration_minutes = 60
conflict_policy = "manual"
allow_attendees = false
# Optional category filter; both keys are required together:
# notion_select_property = "Type"
# notion_select_value = "Research"
# Optional cutoff for unlinked historical items, not linked records:
# import_since = "2026-11-09T00:00:00Z"

[mappings.properties]
title = "Name"
date = "Date"
google_event_id = "NCS Event ID"
description = "Notes"
location = "Location"
timezone = "NCS Time Zone"
google_url = "Calendar Link"
recurrence = "Recurrence"
# Enable only if you created and checked this Checkbox:
# sync_enabled = "Sync enabled"

In /etc/ncs/secrets.env, set the following with your real token. Keep this file root-owned and mode 0600. Do not put credentials in HTML, TOML, shell command arguments or Git.

NOTION_TOKEN='YOUR_INTERNAL_CONNECTION_TOKEN'
# Only used with an optional verified Notion webhook subscription:
NOTION_WEBHOOK_SECRET=''

NOTION_TOKEN is the default secret environment variable; notion_token_env can name another. NOTION_WEBHOOK_SECRET is unused in ordinary polling. A second mapping requires another [[mappings]] and its own [mappings.properties]. Mapping names and Google calendar IDs must be distinct. Sharing a Notion source is allowed only with distinct values of the same Select filter.

Authorize Google from a browser computer

On a Mac or Linux computer with Python 3.11+ and a browser, extract the same source release. Create a virtual environment and install the local package:

cd notion-calendar-sync-0.2.3
python3 -m venv .venv
.venv/bin/python -m pip install .
cp examples/config.toml authorize.toml
# Edit authorize.toml: use absolute LOCAL google_client_path,
# google_token_path and state_path, plus your real mapping IDs/names.
.venv/bin/ncs --config authorize.toml authorize

On Windows, install Python 3.11+ from its official distributor for this source-based authorization route, then use PowerShell. The desktop extra supplies time-zone data that Windows does not provide in the same format as Unix:

cd notion-calendar-sync-0.2.3
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[desktop]"
Copy-Item examples\config.toml authorize.toml
# Edit authorize.toml with absolute LOCAL paths and your mapping.
# TOML Windows paths can use forward slashes, for example C:/Users/NAME/…
.\.venv\Scripts\ncs.exe --config authorize.toml authorize

Place the Google Desktop client JSON at the local google_client_path. The command opens the browser on this computer and creates the local google_token_path after consent. Complete consent within five minutes while the command remains running. If it times out, run authorization again and use its new browser request. Do not open that authorization URL on a different computer from the receiver. --no-browser only suppresses launching the browser; it does not create a remote or copy-and-paste OAuth flow.

Transfer both files over SSH. Replace every placeholder with your own file paths, SSH username and Pi host. SSH is an encrypted remote connection; these commands do not require publishing a web endpoint. The chmod line below is for macOS/Linux; on Windows keep the files inside your private user profile and use scp with Windows paths. Run the sudo installation lines on the Pi.

chmod 600 /LOCAL/PATH/google-token.json /LOCAL/PATH/google-client.json
scp /LOCAL/PATH/google-token.json PI_USER@PI_HOST:/tmp/ncs-google-token.json
scp /LOCAL/PATH/google-client.json PI_USER@PI_HOST:/tmp/ncs-google-client.json

# Then on the Pi:
sudo install -o ncs -g ncs -m 0600 /tmp/ncs-google-token.json /var/lib/ncs/google-token.json
sudo install -o root -g ncs -m 0640 /tmp/ncs-google-client.json /etc/ncs/google-client.json
rm /tmp/ncs-google-token.json /tmp/ncs-google-client.json
sudo ncs-control inspect
sudo ncs-control dry-run

Delete temporary local authorization files when no longer needed, or keep them only in protected credential storage. The service refreshes its Google token automatically and writes replacements atomically. On reauthorization, replace the token, retain SQLite and rerun inspection.

For an existing third-party pair, obtain the actual Notion page UUID and Google event id in the selected calendar. The Google events.list API Explorer can retrieve it. iCalUID and a Google Calendar UI link are not the API event ID. Verify that both objects are the intended logical item, then preview and apply the exact pair:

sudo systemctl stop ncs
sudo ncs-control link --mapping calendar --notion NOTION_PAGE_UUID --google GOOGLE_EVENT_ID
sudo ncs-control link --mapping calendar --notion NOTION_PAGE_UUID --google GOOGLE_EVENT_ID --apply
sudo ncs-control dry-run

Repeat only for verified identities. Differences can become reviewable conflicts. The CLI's mapping name must equal your configured name. A new Google event on an already populated calendar also imports unless it is unsupported or protected by an import_since cutoff. The cutoff reports older unlinked items for explicit review; it does not infer links.

Apply once, then enable continuous operation

After reviewing the read-only dry run and resolving unwanted creates, run:

sudo ncs-control sync
sudo systemctl enable --now ncs
sudo systemctl status ncs
sudo ncs-control status
sudo journalctl --namespace=ncs -u ncs -f

# Later controls:
sudo systemctl stop ncs
sudo systemctl start ncs
sudo systemctl restart ncs

Unlike the desktop, the CLI does not have a confirmation dialog: sync and enabling the service authorize remote changes. Stop the service before running manual write commands or a dry run against its state. ncs-control loads the same protected environment and runs the CLI as the service account. For another installation the equivalent command is ncs --config /PATH/config.toml COMMAND.

Schedule, efficiency and optional notifications

Polling checks for changes every 45 seconds by default, with a full reconciliation every 900 seconds. Reconciliation means re-reading complete current membership to repair missed changes. Google normally uses an incremental change token; expired tokens trigger a full fetch without discarding item mappings. Notion's default full active/archived membership scans detect missing linked pages for a confirming read. notion_incremental = true uses edited-time queries to reduce transferred scan data, but Trash detection can then wait for reconciliation or a verified notification. Keep the default for prompt deletion checks.

The desktop exposes both intervals. The server uses poll_seconds and reconcile_seconds; polling must be at least 5 seconds and full checks no shorter than polling. A 45-second check interval is not a five-second end-to-end guarantee. Provider response time, notification delivery, throttling and outages affect completion. Compressed API responses, Google incremental listings, pagination, bounded backoff and durable retries reduce traffic and recover without losing the journal.

For one light mapping fitting each listing page, unchanged 45-second polling normally makes about 5,760 Notion and 3,840 Google requests per day, before writes, retries and extra pages. Normal use requires no paid hosting or tunnel. API quotas, workspace limits and Google policies can change; inspect your project's current quota before large imports. See Notion request limits and Google usage limits.

Optional advanced server webhooks

A webhook is an incoming change notification. This server supports authenticated notifications as signals to fetch current data, while polling remains active. The desktop wizard uses polling and does not provision public hosting. Only configure this option if you already operate a stable, publicly reachable HTTPS reverse proxy. No paid tunnel is required or supplied.

Forward only /webhooks/notion and /webhooks/google to the Pi's default 127.0.0.1:8765 receiver. Terminate TLS at the proxy and limit request bodies to 256 KiB. Set public_url = "https://YOUR_HOST" in [service]; optional receiver keys are webhook_host and webhook_port.

Create the Notion subscription at https://YOUR_HOST/webhooks/notion for relevant page creation, content and property updates, move, deletion/restore and schema changes. With the normal worker stopped, run sudo ncs-control webhook-verify --output /var/lib/ncs/notion-candidate.txt --timeout 300. Trigger the subscription handshake. The new mode-600 candidate file is untrusted until its value is accepted in Notion's Verify form. Read it privately, complete verification, then set that verified value as NOTION_WEBHOOK_SECRET. Set notion_webhook_subscription and notion_webhook_workspace in [service] to the subscription/workspace IDs; remove the candidate file and restart.

When public_url is set, Google calendar watch channels are created and renewed automatically. Their persisted token, resource identity and expiration are validated. Notion notifications require a valid HMAC, a cryptographic signature made with the verified shared secret, and the configured subscription/workspace. Duplicate notifications are deduplicated. Neither payload directly edits an item. Failed delivery or renewal leaves polling and reconciliation available.

Hosting and TLS configuration depend on your network and proxy and are not automated by this package. Official references: Notion webhooks, delivery behavior, and Google push channels.

9. Test the connection with disposable items.

Run these checks in a dedicated source/calendar pair before applying the tool to your working calendar. Give every test item a unique name so you can inspect its identity, but do not use its name as proof that two records are linked.

  1. Connect and inspect access, map the required properties, preview and approve the empty test setup. If a participation Checkbox is mapped, check it on new Notion test entries.
  2. Create one ordinary timed Notion entry with a title, Date and mapped notes. Wait for detection and processing. Confirm exactly one Google event, a filled event-ID marker and the expected link.
  3. Edit that Google event's title, time and mapped location. Confirm the same Notion page changes and its event ID remains identical. Then edit Notion notes and verify the same Google event changes.
  4. Create a second ordinary event directly in Google with no attendees. Confirm exactly one new Notion entry. Change it to a multi-day all-day event and check both end-date displays using the rules below. Test a time-zone change if you mapped the zone field.
  5. Wait through repeated checks and a full reconciliation, then restart the application or service. Confirm both logical items remain single pairs, with no extra creates. Inspect the dashboard or status and operations for pending work.
  6. Move the first test Notion page to Trash and verify the linked Google event is cancelled. Delete the second test event in Google and verify its linked Notion page is trashed. Do not substitute clearing a Date or hiding an entry in a view.
  7. For conflict testing, pause the worker, edit the same mapped field differently on both sides, then resume. Confirm a conflict retains both versions. Review and deliberately choose a provider; other items should continue. Test only disposable data.

If any step fails, pause before retrying a creation. Inspect the existing identity and pending operation rather than deleting state. These account-specific checks require your own credentials. Publishing this website does not execute them against your accounts.

10. Understand supported behavior.

Fields, dates and time zones

Ordinary supported events synchronize title and the complete time range in both directions, plus configured description, location and recurrence. Peer links and stable identities are managed by the service. Unmapped optional fields are not imported or overwritten. Only changed mapped fields are patched; Notion page blocks are never edited.

Description mapping keeps literal source text. Google's <b>Review</b> remains those literal characters in Notion Text, rather than being repeatedly converted between HTML and Markdown. Plain text works too. Rich formatting and mentions inside mapped Text/title properties are outside this format; partial/paginated rich content is reported instead of silently truncated.

Notion's all-day range includes its last date. Google's all-day end is exclusive. A Notion October 30–31 range becomes Google start October 30, end November 1; a single date becomes one day. Missing timed ends use the configured duration. A multi-day item remains one logical pair.

Timed events preserve instants and use a regional IANA zone. With a zone Text mapping, Notion endpoints are stored in UTC while the zone property retains the intended region, avoiding daylight-saving endpoint coercion. Notion's Date display may consequently show UTC. Invalid or nonexistent times, mixed date/timestamp ranges and ambiguous times without a usable offset are held and reported, rather than silently shifted. Start, end, all-day status, zone and recurrence are treated as one related conflict group.

Some provider saves return a different mapped value from the requested one. The service retains the original request and the returned value as a manual conflict, including under automatic conflict policies. It keeps the existing item identities and does not treat that changed save result as a new user edit to copy back. Other items continue synchronizing.

A live Google API check exposed this for an America/Denver range spanning the two copies of the repeated autumn hour: a requested 90-minute interval was returned as 30 minutes. Sending UTC timestamps with that named zone did not prevent the change. The service preserves the original range and reports Provider changed a saved value for review. An explicitly reviewed UTC event zone can preserve the tested one-off interval; the integration does not silently change a recurring series to UTC or claim that every repeated-hour range is supported automatically.

Duplicates, feedback loops and conflicts

SQLite records each page/event pair, the last synchronized values and provider versions. Stable IDs, a durable operation journal, confirming reads and service-owned markers allow repeated checks and interrupted-write recovery without deliberately replaying a possibly successful create. Uncertain creates can remain blocked for review instead of risking a duplicate. A local single-worker lock does not coordinate separate computers or third-party tools.

Independent edits to different mapped fields merge. Incompatible edits to the same field, or to the related time/recurrence group, become persistent conflicts under the default manual policy. A provider-changed save remains a manual hold even when an automatic conflict policy is configured. Both observations and their baseline are retained. In the desktop conflict view, choose the intended provider after reviewing the values; resolution pauses synchronization, so choose Resume afterward.

sudo ncs-control conflicts
sudo ncs-control conflicts CONFLICT_ID
sudo systemctl stop ncs
sudo ncs-control resolve CONFLICT_ID --prefer notion
# Or choose --prefer google after reviewing both versions.
sudo systemctl start ncs

Server alternatives conflict_policy = "notion" or "google" explicitly choose that provider for incompatible fields and can discard the competing value. They are not the default and are not exposed in the desktop wizard. They do not automatically accept a provider-changed save. If either item changes while a conflict is being reviewed, inspect the refreshed conflict before resolving again.

Deletion and paused items

A positively confirmed Notion Trash state or Google status=cancelled propagates to its supported, linked, in-scope peer. The tool keeps a tombstone, a retained record of the deleted pair, to prevent automatic recreation. Provider Trash retention and recovery limits still apply. A deletion concurrent with an edit becomes a manual conflict.

Permission loss, 401/403/404 responses, failed requests, incomplete pagination and an item missing from a query do not prove deletion. Clearing a Date, unchecking participation, changing category, moving out of scope or archiving from a data-source view suspends the relationship and retains its peer. Restoring one resource alone does not resurrect the pair. Restore both deliberately in their provider interfaces and explicitly relink the same live IDs through the CLI before reactivating; this release has no desktop restore/relink wizard.

Recurring series and exceptions

Notion's Date property is not a recurrence-rule API. The optional Text property stores RFC 5545 recurrence source, a standard notation, with one RRULE:, RDATE: or EXDATE: line per line. For example, RRULE:FREQ=WEEKLY;BYDAY=MO;COUNT=8 describes eight weekly Monday occurrences, starting from the mapped Date. Start/end belong in Date, not DTSTART/DTEND recurrence lines.

  • One Notion page represents a Google recurring master. Supported series title, time, notes, location and rule edits synchronize in both directions.
  • Ordinary generated occurrences are not expanded into unlimited Notion entries. An explicitly modified Google occurrence can have its own linked page. Its immutable parent/original-start identity ensures edits affect only that occurrence.
  • Cancelling a linked occurrence trashes that occurrence's page; trashing its exception page cancels only that instance. A never-imported cancelled occurrence does not need a live Notion page.
  • Creating an unlinked exception in Notion is unsupported. Google's “this and following” operation can split a series into separate masters, which remain distinct identities.
  • Without a recurrence mapping, recurring items are reported and preserved. Unsupported rules or special provider semantics are held rather than flattened.

See Google's series and exception model and event fields and all-day dates.

Meetings and other exclusions

Events with attendees are excluded from default writes and deletions, including linked events that later gain attendees. Attendee invitations, RSVP changes, conference creation, locked events and special event types such as birthdays, focus time, out-of-office and working location are outside the default mapping. The server's allow_attendees = true is an explicit advanced opt-in to event-field writes using sendUpdates=none; it still does not map attendees or guarantee that Google sends no email. Keep it false for this setup.

Unrelated Google metadata is omitted from patches. A live provider check found one material normalization: converting timed events to all-day can turn inherited default reminders into explicit alarms. Current effective alerts were retained, but they might no longer follow later calendar-default changes. Do not assume every raw provider field remains byte-for-byte identical.

11. Operate, back up and upgrade.

The dashboard shows health, last successful sync, pending work and conflicts. Closing the desktop window minimizes it; use Quit to stop background work. Optional Start at login runs for your user after login. A supervisor restarts crashes, and persisted work resumes after connectivity returns. Export redacted diagnostics for counts and sanitized errors; review any export before sharing it.

Desktop settings, SQLite and local backups live in ~/Library/Application Support/Notion Calendar Sync/ on macOS or %LOCALAPPDATA%\Notion Calendar Sync\ on Windows. Credentials are separate in Keychain/Credential Manager. Pause and Quit before making a complete copy of this directory. Local state and conflict backups contain private event data. They are not provider-wide exports.

On the Pi, create a consistent SQLite backup with a new filename, and protect configuration/client/token copies separately. Do not copy only an actively changing SQLite file while ignoring its journal.

sudo ncs-control backup /var/lib/ncs/backup-UNIQUE_DATE.sqlite3
sudo tar -czf /var/lib/ncs/private-config-UNIQUE_DATE.tar.gz -C /etc ncs
sudo chmod 600 /var/lib/ncs/private-config-UNIQUE_DATE.tar.gz
# Also protect /var/lib/ncs/google-token.json in your credential backup.

Keep encrypted/off-device copies with your existing backup system; this service does not automatically prune dated backups. Restore with the worker stopped, preserve the current database and any WAL/SHM files first, and restore a consistent state/configuration set with the documented owners and modes. A newly authorized token should not be needlessly replaced with an old one. Reconnect accounts on another computer, inspect and preview a full reconciliation before resuming. Deleting SQLite history while leaving both providers populated can defeat duplicate prevention.

For upgrades, pause/stop, back up, retain the old release, replace the desktop bundle or rerun the Pi installer from the new source, inspect and preview before restarting. Windows installer upgrades must run after all app copies quit. The installer stages the new program and retains recovery material. There is no automatic remote code updater.

The Pi service restarts after a crash and boots through systemd. Its namespaced journal is bounded to 50 MB persistent / 10 MB runtime and 14 days. View it using the journalctl --namespace=ncs command above. To uninstall, disable startup or sudo systemctl disable --now ncs, then remove the application/code and service files. Retain configuration, state and credential backups until you deliberately discard them. Uninstalling does not delete provider records. Revoke Google and Notion access separately if disconnecting permanently.

12. Troubleshoot setup.

Troubleshooting. Scroll horizontally.
SymptomCheck and recovery
Notion connection validates but database is absentGrant Content access to the actual database/parent. Check workspace, ID and the selected data source. A valid token does not imply database access.
Wrong property type or missing mappingUse Title, Date and Text identity properties. Check exact names and types. A formula cannot serve as a writable Date. Omit unwanted optional mappings rather than using empty or invented types.
Google authorization blocked or API disabledEnable Google Calendar API in the project owning the client. Use Desktop app JSON with an installed section, the correct account and test-user membership. Check organization policy and requested scopes.
Redirect mismatch or browser cannot finishUse a Desktop client and authorize on the same computer as the callback listener. Keep the app or authorization command running and finish within five minutes. A timed-out receiver needs a new authorization attempt. If the app already reports connected, refreshing its completed callback page can show a connection error because that temporary receiver has closed. Do not substitute the website/privacy URL. Check local firewall restrictions; recreate an incorrect Web client as a Desktop client.
Stops after about seven days / invalid_grantCheck External Testing status, switch to production where applicable and reauthorize. Revoked/expired grants also need reconnection. Keep existing SQLite state.
Calendar missing or read-onlySign in to the account with owner/writer access. Refresh calendar discovery or set its stable Calendar ID on the server. An API key or read-only scope is insufficient.
No event appearsCheck Date, Checkbox/category filters, attendees, recurrence mapping, special event type and unsupported diagnostics. Check that the host is awake and worker running. Wait for a check cycle; inspect queued work.
Date cleared but event remainsExpected paused behavior. Explicitly trash a supported linked page or cancel its event to propagate deletion.
429 / 529 / Google quota errorsLeave queued state intact; bounded retries and later cycles recover. Check provider quota/workspace capacity and reduce the participating workload or lengthen polling when required. Do not repeatedly restart to bypass backoff.
Access/404 or missing query resultRestore permissions or scope and reconcile. It is not deletion evidence and must not cause a manual peer deletion.
App lock, repeated creates or unexpected import previewStop other writers. Check exact event/page IDs and retained state before applying anything. Do not merge solely by title/date or delete the journal. Unlinked copies need explicit identity review.
Uncertain Notion create remains blockedUse operations to inspect its recovery ID; check active entries and Trash for its exact marker. Do not blindly retry a possibly successful create. The advanced retry-operation ID --acknowledge-no-remote-create command is only for positively verified absent remote creates.
OS blocks app or secure storageCheck the download checksum and ordinary OS approval. Ensure Keychain/Credential Manager is available for your signed-in user. Use the Windows .cmd launcher if Script Host is disabled, subject to organization policy.

What has actually been tested?

Release 0.2.3 ran 282 passing tests on native Windows Server 2025 x64 and 281 passing tests plus one Windows-only skip on native Intel macOS 15.7.9. Each platform passed 43 controlled desktop setup/sync acceptance checks using the real controller, API adapters, journal and SQLite with controlled provider responses and a real local OAuth callback. Native credential stores, packaged windows and recovery were checked separately. An additional 43-check Windows run used actual Credential Manager with disposable values and positively removed them afterward. Windows 10/11 client builds and every older macOS release were not separately executed.

A new live Mac run passed 77 assertions across two disposable pairs, including both creation/edit/deletion directions, normal daylight-saving changes, conflict resolution, restarts, metadata preservation and the provider-changed-save safeguard. All four linked records were positively trashed/cancelled; final searches found no remaining live test copies. Real Google browser consent completed separately in the first run; the passing regression retest reused an existing grant. Windows used controlled provider responses, not private live account credentials. See the full release report for the initial failure, fixes, cleanup and exact platform/interaction boundaries.

This website guide was checked separately for navigation, downloads and responsive layout. Those website checks do not test your credentials, hosting or live calendar synchronization. Optional public HTTPS/proxy provisioning, historical desktop state migration/relinking and account-administrator approvals are not automated setup flows in this release.