Notion Provision

notion-provision

Create Notion section pages and databases from a YAML spec. Idempotent — re-running the same spec against the same root page reuses existing pages/DBs and only adds missing properties.

Prerequisites

• NOTION_API_KEY env var (or .env file, or .vscode/mcp.json)
• A root page in the target Notion workspace, shared with the integration
• The page's ID (32-char hex, can be UUID-dashed or not)
• pyyaml installed in your environment
• notion-os-toolkit available (via pip or local sibling repo)

Steps

1. Ask the user for the path to their YAML spec file (or build one if they describe sections + DBs in natural language).
2. Confirm the root page ID and that the integration is shared on it.
3. Read the spec and validate: required keys are root_page_id, sections[].title, sections[].databases[].name, sections[].databases[].properties.
4. Run:

   from notion_os_toolkit import auth, client, provisioner
   nc = client.NotionClient(auth.load_token())
   ids = provisioner.provision_from_yaml(nc, "<spec-path>", out_path="ids.json")
   

5. If the spec has cross-DB relations, do them in a second pass (each relation property requires the target DB to already exist). Pattern:

   nc.update_database(source_id, properties={
       "ClientRelation": {"relation": {"database_id": clients_db_id, "single_property": {}}},
   })
   

6. Report back: number of sections created, number of DBs created, path to ids.json.

YAML spec shape

root_page_id: "abc123..."
sections:
  - title: CRM
    icon: 👥
    databases:
      - name: Leads
        icon: 🎯
        properties:
          Lead Name: {title: {}}
          Lead Stage:
            select:
              options:
                - {name: Initial Contact}
                - {name: Won}

Input/Output contract

Input: spec file path + root page ID Output: ids.json mapping section titles + DB names to Notion IDs

When NOT to use this skill

• If the workspace already exists and you just need to add ONE new DB — call the API directly with nc.create_database.
• If the user wants to seed data — use notion-seed instead.
• If the user wants helper formulas added — use notion-helper-formulas.

Example invocation

User: "Build me a CRM in Notion with Leads, Clients, and Activities databases."

You: Draft a YAML spec covering those three DBs with reasonable properties. Confirm with user. Provision.

Reference

• scripts/run.py — minimal driver script
• Notion API docs: https://developers.notion.com/reference/create-a-database