Notion Google Contacts Worker

A Notion Worker that syncs your Google Contacts into a managed Notion database every 3 hours.

• One-way sync: Google → Notion (contacts removed in Google are removed from Notion on the next full sync)
• Hosted by Notion: no servers or cron jobs to run yourself
• OAuth: Google authorization is handled by the Workers runtime

Beta: Notion Workers is in beta. APIs, CLI commands, and hosting behavior may change. See the Workers documentation.

Prerequisites

• A Notion workspace with Workers enabled (Business or Enterprise; workspace owner must enable Workers)
• Node.js 22+
• The Notion CLI (ntn)
• A Google Cloud project with the People API enabled

Quick start

1. Clone and install

git clone https://github.com/simosme/notion-google-contacts-worker.git
cd notion-google-contacts-worker
npm install

2. Install the Notion CLI

curl -fsSL https://ntn.dev | bash
ntn login

On Windows, follow the CLI installation docs if the install script is not available.

3. Deploy the worker (first time)

From the project directory:

ntn workers deploy

This registers the worker with your Notion workspace. OAuth credentials are not required yet.

4. Google Cloud setup

1. Create or select a Google Cloud project.

2. Enable the People API.

3. Configure the OAuth consent screen (External or Internal as appropriate).

4. Create an OAuth 2.0 Client ID (application type: Web application).

5. Get the Notion redirect URL:

   ntn workers oauth show-redirect-url

6. Add that URL as an Authorized redirect URI on your Google OAuth client.

7. Copy the Client ID and Client secret.

Required OAuth scope (requested by this worker):

• https://www.googleapis.com/auth/contacts.readonly

5. Store secrets and redeploy

ntn workers env set GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret
ntn workers deploy

6. Authorize Google

ntn workers oauth start googleAuth

Complete the browser flow to grant read access to your contacts.

7. Run a sync

Preview without writing to Notion:

ntn workers sync trigger contactsSync --preview

Run a real sync immediately:

ntn workers sync trigger contactsSync

Check sync status:

ntn workers sync status

After the first successful sync, Notion creates a Google Contacts database in your workspace. The worker runs automatically every 3 hours.

What gets synced

Each Google contact becomes one row with:

Notion property	Source
Name	Primary display name
Contact ID	Google resourceName (stable key)
Email	Primary email
Phone	Primary phone
Company	Primary organization (name and title)
Photo URL	Primary photo URL

Development

npm run check   # TypeScript type-check
npm run build   # Emit dist/

Pull secrets for local testing (includes a refreshed OAuth token):

ntn workers env pull

See .env.example for variable names. Never commit .env.

Schedule and sync behavior

• Schedule: 3h (every 3 hours), configured on the contactsSync capability in src/index.ts.
• Mode: replace — each full sync cycle paginates through all Google contacts; records not seen in that cycle are deleted from Notion.
• Pagination: 100 contacts per API page; the sync resumes with pageToken until hasMore is false.

For very large address books, consider switching to incremental mode and Google’s syncToken API (see People API contacts guide).

Useful CLI commands

ntn workers deploy
ntn workers sync trigger contactsSync
ntn workers sync trigger contactsSync --preview
ntn workers sync status
ntn workers sync state reset contactsSync
ntn workers capabilities disable contactsSync
ntn workers capabilities enable contactsSync
ntn workers runs logs <runId>

Security

• Do not commit GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, or .env.
• Each user deploys this worker to their own Notion workspace and authorizes their own Google account.
• OAuth tokens are stored by the Notion Workers runtime, not in this repository.

License

MIT — see LICENSE.