Skip to content
Back to search

notion-cookbook

Hub for getting started with Notion, including documentation, customizable scripts, and quick-start guides.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/makenotion/notion-cookbook with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/makenotion/notion-cookbook'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/makenotion--notion-cookbook/badge.svg)](/listings/makenotion--notion-cookbook)

HTML

<a href="/listings/makenotion--notion-cookbook"><img src="/api/listings/makenotion--notion-cookbook/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 185 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Notion cookbook
  2. Working examples, guides, and agent skills for building with the Notion API
  3. and [Notion Workers](https://developers.notion.com/docs/workers). Every example
  4. is self-contained: choose a task, open its README, and run it from its own
  5. directory.
  6. ## What do you want to build?
  7. - **Learn the Notion API:** start with
  8. [Introduction to the Notion API](examples/intro-to-notion-api/), then explore
  9. [block text parsing](examples/parse-text-from-any-block-type/) or
  10. [large data source queries](examples/query-large-data-sources/).
  11. - **Build an API integration:** create a
  12. [web form](examples/web-form-with-express/), connect
  13. [GitHub issues](examples/notion-github-sync/), or send
  14. [email notifications](examples/database-email-update/).
  15. - **Bring external data into Notion:** use a Worker sync for
  16. [GitHub issues and pull requests](workers/templates/github-sync/),
  17. [GitHub stars](workers/templates/github-stars-sync/), [HubSpot](workers/templates/hubspot-sync/),
  18. [Intercom](workers/templates/intercom-sync/),
  19. [Linear](workers/templates/linear-sync/), [PagerDuty](workers/templates/pagerduty-sync/),
  20. [Readwise and Reader](workers/templates/readwise-sync/),
  21. [Salesforce](workers/templates/salesforce-sync/), [Sentry](workers/templates/sentry-sync/),
  22. [Todoist](workers/templates/todoist-sync/), [Zendesk](workers/templates/zendesk-sync/) and more.
  23. - **Give a Notion Agent a reliable new capability:** execute a repeatable API
  24. workflow in one tool call, or connect to [Airflow](workers/templates/airflow/), [Vega-lite charts](workers/templates/chart-generator/),
  25. [CloudWatch Logs](workers/templates/cloudwatch-logs/),
  26. [Postgres](workers/templates/postgres-query/), [Snowflake query](workers/templates/snowflake-query/), [PowerPoint creator](workers/templates/powerpoint-creator/), [Vercel](workers/templates/vercel-production-deployment-tools/), and more.
  27. - **React to external events:** receive and verify
  28. [Zendesk webhooks](workers/templates/zendesk-webhook/).
  29. ## Quickstarts
  30. ### Using this cookbook with a coding agent
  31. Tell the agent the outcome or integration you need, then point it to:
  32. - [`catalog.json`](catalog.json), the machine-readable index of every runnable
  33. project and its supported commands.
  34. - [`AGENTS.md`](AGENTS.md), the canonical instructions for finding, running,
  35. adapting, adding, and validating recipes.
  36. - The selected project's README and entrypoint, which are authoritative for its
  37. setup and implementation.
  38. For example: "Use `catalog.json` to find the Linear sync recipe. Explain its
  39. data flow, adapt it to include issue labels, and run its offline checks."
  40. ### Run an API example
  41. The introductory example is the best first project. Create a
  42. [Notion integration](https://www.notion.com/my-integrations), share a test page
  43. with it, then:
  44. ```sh
  45. git clone https://github.com/makenotion/notion-cookbook.git
  46. cd notion-cookbook/examples/intro-to-notion-api
  47. npm install
  48. cp .env.example .env
  49. # Add NOTION_API_KEY and NOTION_PAGE_ID to .env
  50. npm run basic:1
  51. ```
  52. Other API examples use different scripts and may require additional services.
  53. Use the command in the selected example's README rather than assuming
  54. `npm start`.
  55. ### Deploy a Worker
  56. The DuckDB query Worker is self-contained and needs no secrets:
  57. ```sh
  58. npm install --global ntn
  59. git clone https://github.com/makenotion/notion-cookbook.git
  60. cd notion-cookbook/workers/templates/duckdb-query
  61. npm install
  62. npm run check
  63. npm test
  64. ntn login
  65. ntn workers deploy --name duckdb-query
  66. ```
  67. After deployment, add the Worker to a custom agent under **Tools and access >
  68. Add connection**. Other Workers may need service credentials or database
  69. configuration; follow their READMEs.
  70. ## API examples
  71. These examples use the official JavaScript SDK and run locally with Node.js.
  72. See the [API examples guide](examples/) for shared setup information.
  73. | Task | Example | Integrations |
  74. | ------------------------------------------------------------ | -------------------------------------------------------------------------- | -------------------- |
  75. | Learn blocks, pages, databases, queries, and file uploads | [Introduction to the Notion API](examples/intro-to-notion-api/) | Notion API |
  76. | Send an email when a database status changes | [Database email update](examples/database-email-update/) | Notion API, SendGrid |
  77. | Fill a database with correctly typed sample rows | [Generate random data](examples/generate-random-data/) | Notion API |
  78. | Copy GitHub issues into a Notion database | [Notion–GitHub issue sync](examples/notion-github-sync/) | Notion API, GitHub |
  79. | Update Notion tasks when linked pull requests close or merge | [Notion task–GitHub PR sync](examples/notion-task-github-pr-sync/) | Notion API, GitHub |
  80. | Extract plain text from Notion blocks | [Parse text from any block type](examples/parse-text-from-any-block-type/) | Notion API |
  81. | Read beyond the 10,000-row query limit | [Query large data sources](examples/query-large-data-sources/) | Notion API |
  82. | Create databases, pages, blocks, and comments from a web UI | [Web form with Express](examples/web-form-with-express/) | Notion API, Express |
  83. ## Worker examples
  84. Workers are server-side extensions deployed to Notion. A **sync** maintains a
  85. managed Notion database, a **tool** gives a Notion Agent a callable capability,
  86. and a **webhook** handles events from another service. See the complete
  87. [Workers guide](workers/) for setup and deployment.
  88. ### Default template
  89. | Task | Worker |
  90. | -------------------------------------------- | ------------------------------------------------------------- |
  91. | Scaffold a new Worker from the base template | [Default Worker template](workers/templates/workers-default/) |
  92. ### Sync external data into Notion
  93. | Task | Worker | Source |
  94. | -------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- |
  95. | Learn the sync pattern with seeded, in-memory data | [DuckDB sync](workers/templates/duckdb-sync/) | DuckDB |
  96. | Turn starred repositories into a research library | [GitHub stars sync](workers/templates/github-stars-sync/) | GitHub |
  97. | Sync issues and pull requests | [GitHub sync](workers/templates/github-sync/) | GitHub |
  98. | Sync contacts, deals, and companies | [HubSpot sync](workers/templates/hubspot-sync/) | HubSpot |
  99. | Sync companies, contacts, conversations, and tickets | [Intercom sync](workers/templates/intercom-sync/) | Intercom |
  100. | Sync issues, sprints, analytics, and projects | [Jira sync](workers/templates/jira-sync/) | Jira Cloud |
  101. | Sync projects, issues, and initiatives | [Linear sync](workers/templates/linear-sync/) | Linear |
  102. | Monitor PagerDuty incidents and service readiness in Notion | [PagerDuty sync](workers/templates/pagerduty-sync/) | PagerDuty |
  103. | Turn saved sources and highlights into project evidence | [Raindrop.io research library sync](workers/templates/raindrop-sync/) | Raindrop.io |
  104. | Build a related reading library and highlight knowledge base | [Readwise and Reader sync](workers/templates/readwise-sync/) | Readwise |
  105. | Sync accounts and opportunities | [Salesforce sync](workers/templates/salesforce-sync/) | Salesforce |
  106. | Coordinate issue triage, service risk, and rollout health | [Sentry sync](workers/templates/sentry-sync/) | Sentry |
  107. | Sync the result of a warehouse query | [Snowflake sync](workers/templates/snowflake-sync/) | Snowflake |
  108. | Sync open tasks and project summaries with recent completion context | [Todoist sync](workers/templates/todoist-sync/) | Todoist |
  109. | Sync an employee-facing directory | [Workday employee directory sync](workers/templates/workday-sync/) | Workday |
  110. | Sync related tickets, users, organizations, and metrics | [Zendesk sync](workers/templates/zendesk-sync/) | Zendesk |
  111. ### Add tools to a Notion Agent
  112. An agent tool can coordinate a workflow across multiple apps. For example, the
  113. [Sentry to PagerDuty incident tools](workers/templates/sentry-pagerduty-incident-tools/)
  114. find and inspect an issue in Sentry, then declare an incident in PagerDuty.
  115. | Task | Worker | Integration |
  116. | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- |
  117. | Inspect DAGs, runs, tasks, and logs | [Airflow](workers/templates/airflow/) | Apache Airflow |
  118. | Render and insert Vega-Lite charts | [Chart generator](workers/templates/chart-generator/) | Vega-Lite |
  119. | Browse log groups, streams, and events | [CloudWatch Logs](workers/templates/cloudwatch-logs/) | AWS CloudWatch Logs |
  120. | Learn the database-query pattern with seeded data | [DuckDB query](workers/templates/duckdb-query/) | DuckDB |
  121. | Review and publish an existing draft release | [GitHub draft release tools](workers/templates/github-draft-release-tools/) | GitHub |
  122. | Query a database with read-only SQL | [Postgres query](workers/templates/postgres-query/) | PostgreSQL |
  123. | Turn a Notion page into PowerPoint slides (`.pptx`) | [PowerPoint creator](workers/templates/powerpoint-creator/) | Notion, PowerPoint |
  124. | Find Sentry issues and declare PagerDuty incidents | [Sentry to PagerDuty incident tools](workers/templates/sentry-pagerduty-incident-tools/) | Sentry, PagerDuty |
  125. | Query a warehouse with read-only SQL | [Snowflake query](workers/templates/snowflake-query/) | Snowflake |
  126. | Learn the database-query pattern with seeded data | [SQLite query](workers/templates/sqlite-query/) | SQLite |
  127. | Inspect, promote, or roll back a Vercel deployment | [Vercel production deployment tools](workers/templates/vercel-production-deployment-tools/) | Notion, Vercel |
  128. ### Handle webhooks
  129. | Task | Worker | Integration |
  130. | ---------------------------------------------------- | ----------------------------------------------------- | ----------- |
  131. | Verify ticket events and upsert tickets and comments | [Zendesk webhook](workers/templates/zendesk-webhook/) | Zendesk |
  132. ## More resources
  133. - [Developer guides](docs/) — including the
  134. [Notion MCP client integration guide](docs/mcp-client-integration.md)
  135. - [Agent skills](skills/) — reusable Notion workflows for any MCP client
  136. - [Plan marketing campaigns](skills/mcp-clients/plan-marketing-campaigns/SKILL.md) — Connect campaign briefs, content production, and brand resources.
  137. - [Create my team handbook](skills/mcp-clients/create-my-team-handbook/SKILL.md) — Find complete procedures and handle operational requests.
  138. - [Set up my project](skills/mcp-clients/set-up-my-project/SKILL.md) — Build an EPD home with tasks, docs, meeting notes, and progressive team and placement refinement.
  139. - [Organize my semester](skills/mcp-clients/organize-my-semester/SKILL.md) — Create a personal study space with course notes and upcoming assignments.
  140. - [Build my engineering wiki](skills/mcp-clients/build-my-engineering-wiki/SKILL.md) — Navigate setup, current architecture, operations, and proposals.
  141. - [Notion developer documentation](https://developers.notion.com)
  142. - [Notion API reference](https://developers.notion.com/reference)
  143. - [Contributing](CONTRIBUTING.md) — add or improve an example, Worker, skill, or
  144. guide
  145. ## Community
  146. - [Notion Developers Slack](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg)
  147. - [Stack Overflow](https://stackoverflow.com/questions/tagged/notion-api)
  148. ## License
  149. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.