███╗   ██╗ ██████╗ ████████╗██╗ ██████╗ ███╗   ██╗
████╗  ██║██╔═══██╗╚══██╔══╝██║██╔═══██╗████╗  ██║
██╔██╗ ██║██║   ██║   ██║   ██║██║   ██║██╔██╗ ██║
██║╚██╗██║██║   ██║   ██║   ██║██║   ██║██║╚██╗██║
██║ ╚████║╚██████╔╝   ██║   ██║╚██████╔╝██║ ╚████║
╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═══╝

# Add the hosted server via Claude Code CLI (Streamable HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add via Claude Code CLI
claude mcp add notion -- npx -y @notionhq/notion-mcp-server

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}

npm install @notionhq/client

import { Client } from "@notionhq/client";

// SDK v5 sends a current default Notion-Version; pass notionVersion to pin one
// (e.g. "2026-03-11" for the Markdown page endpoints).
const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Resolve the data source id for a database (single-source DBs use [0]).
const db = await notion.databases.retrieve({
  database_id: process.env.NOTION_TASKS_DB_ID!,
});
const dataSourceId = db.data_sources[0].id;

// Search for pages
const search = await notion.search({
  query: "API Design",
  filter: { property: "object", value: "page" },
});

// Query a data source (e.g., task tracker) — replaces the removed databases.query
const tasks = await notion.dataSources.query({
  data_source_id: dataSourceId,
  filter: {
    and: [
      { property: "Status", select: { equals: "In Progress" } },
      { property: "Assignee", people: { contains: "me" } },
    ],
  },
  sorts: [{ property: "Due Date", direction: "ascending" }],
});

// Create a new page (row in a data source)
const newTask = await notion.pages.create({
  parent: { type: "data_source_id", data_source_id: dataSourceId },
  properties: {
    Name: { title: [{ text: { content: "Fix auth middleware" } }] },
    Status: { select: { name: "Todo" } },
    Priority: { select: { name: "High" } },
    "Due Date": { date: { start: "2026-08-20" } },
  },
});

// Append content to a page
await notion.blocks.children.append({
  block_id: newTask.id,
  children: [
    {
      object: "block",
      type: "heading_2",
      heading_2: { rich_text: [{ text: { content: "Implementation Notes" } }] },
    },
    {
      object: "block",
      type: "paragraph",
      paragraph: { rich_text: [{ text: { content: "Use JWT with RS256 signing." } }] },
    },
    {
      object: "block",
      type: "code",
      code: {
        language: "typescript",
        rich_text: [{ text: { content: "const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });" } }],
      },
    },
  ],
});

pip install notion-client

from notion_client import Client
import os

notion = Client(auth=os.environ["NOTION_TOKEN"])

# Resolve the data source id, then query it
db = notion.databases.retrieve(database_id=os.environ["NOTION_TASKS_DB_ID"])
data_source_id = db["data_sources"][0]["id"]

results = notion.data_sources.query(
    data_source_id=data_source_id,
    filter={"property": "Status", "select": {"equals": "Done"}},
)

for page in results["results"]:
    title = page["properties"]["Name"]["title"][0]["text"]["content"]
    print(f"Completed: {title}")

import { Client } from "@notionhq/client";
import type { PageObjectResponse } from "@notionhq/client/build/src/api-endpoints";

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function queryAllRows(dataSourceId: string) {
  const rows: PageObjectResponse[] = [];
  let cursor: string | undefined = undefined; // undefined → first page

  do {
    const response = await notion.dataSources.query({
      data_source_id: dataSourceId,
      filter: { property: "Status", select: { equals: "In Progress" } },
      sorts: [{ property: "Due Date", direction: "ascending" }],
      start_cursor: cursor,
      page_size: 100, // max allowed; fewer round-trips
    });

    rows.push(...(response.results as PageObjectResponse[]));
    cursor = response.next_cursor ?? undefined; // null → stop
  } while (cursor !== undefined);

  return rows;
}

const allTasks = await queryAllRows(process.env.NOTION_DATA_SOURCE_ID!);
console.log(`Fetched ${allTasks.length} tasks across all pages`);

import { Client, iteratePaginatedAPI, collectPaginatedAPI } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const data_source_id = process.env.NOTION_DATA_SOURCE_ID!;

// Stream one row at a time — memory-efficient for huge data sources
for await (const row of iteratePaginatedAPI(notion.dataSources.query, { data_source_id })) {
  console.log(row.id);
}

// Collect everything into one array — only when the dataset fits in memory
const allRows = await collectPaginatedAPI(notion.dataSources.query, { data_source_id });
console.log(`Fetched ${allRows.length} rows`);

# Required — internal integration token (prefix ntn_… ; older tokens were secret_…)
NOTION_TOKEN=ntn_...                # From notion.so/profile/integrations

# Optional — IDs for commonly used databases/data sources/pages
NOTION_TASKS_DB_ID=...             # Task tracker database ID (container)
NOTION_DATA_SOURCE_ID=...          # Data source ID inside that DB (query/create target)
NOTION_DOCS_PAGE_ID=...            # Your docs root page ID
NOTION_SPRINT_DB_ID=...            # Sprint planning database

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/notion-update-docs.js"
          }
        ]
      }
    ]
  }
}

import { Client } from "@notionhq/client";
import { execFileSync } from "child_process";

const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Get last commit message
const commitMsg = execFileSync("git", ["log", "-1", "--pretty=%B"]).toString().trim();
if (!commitMsg.startsWith("feat:")) process.exit(0);

// Append to changelog page
await notion.blocks.children.append({
  block_id: process.env.NOTION_CHANGELOG_PAGE_ID,
  children: [{
    object: "block",
    type: "bulleted_list_item",
    bulleted_list_item: {
      rich_text: [{
        text: {
          content: `[${new Date().toISOString().slice(0, 10)}] ${commitMsg}`,
        },
      }],
    },
  }],
});

console.log("Changelog updated in Notion");

Create a new task in the Notion task database for: $ARGUMENTS

Use the Notion MCP to create a page (row) in the tasks data source with:
- Name: $ARGUMENTS
- Status: Todo
- Priority: Medium
- Assignee: (leave blank)
- Source: "Claude Code"

Report the URL of the created Notion page.

# .github/workflows/notion-update.yml
name: Update Notion on Deploy
on:
  workflow_run:
    workflows: ["Deploy to Production"]
    types: [completed]

jobs:
  update-notion:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22' }
      - run: npm install @notionhq/client   # v5+ (data-source model)
      - name: Update Notion
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
          NOTION_SPRINT_DB_ID: ${{ secrets.NOTION_SPRINT_DB_ID }}
        run: |
          node -e "
          const { Client } = require('@notionhq/client');
          const notion = new Client({ auth: process.env.NOTION_TOKEN });
          (async () => {
            const db = await notion.databases.retrieve({ database_id: process.env.NOTION_SPRINT_DB_ID });
            await notion.pages.create({
              parent: { type: 'data_source_id', data_source_id: db.data_sources[0].id },
              properties: {
                Name: { title: [{ text: { content: 'Deployed: ${{ github.sha }}' } }] },
                Status: { select: { name: 'Released' } },
                Date: { date: { start: new Date().toISOString().slice(0,10) } }
              }
            });
            console.log('Notion updated');
          })();
          "