Communitygithub.com

Notion 지식창고

Notion API + ntn CLI: 페이지, 데이터베이스, 마크다운, Workers.

Notion 지식창고란 무엇인가요?

이 스킬은 에이전트가 Notion과 상호작용하는 두 가지 방법(ntn CLI와 HTTP + curl)을 제공합니다. 동일한 통합 토큰으로 두 경로 모두 사용할 수 있으며, macOS/Linux에서는 ntn CLI가 선호되고 Windows에서는 curl이 기본 대안입니다. ntn CLI는 간결한 구문, 원클릭 파일 업로드, Notion Workers(고급 TypeScript 프로그램) 배포 기능을 제공합니다. HTTP 경로는 모든 플랫폼에서 작동하며 특히 Windows 환경에 적합합니다. 이 스킬은 페이지 및 데이터베이스 읽기/쓰기, 마크다운 기반 페이지 생성 및 업데이트, 데이터베이스 쿼리, 파일 업로드, Workers 관리(동기화, 도구, 웹훅) 등 일반적인 Notion API 작업을 다룹니다. 두 경로 모두 2025-09-03 API 버전을 사용하며, 사용자는 Notion 설정에서 통합을 생성하고 대상 페이지/데이터베이스를 공유해야 합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Lord1Egypt/awesome-skill-forge/tree/HEAD/skills/notion

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Notion

Notion과 두 가지 방법으로 대화하세요. 동일한 통합 토큰이 두 방법 모두에서 작동하며, 사용 가능한 방법에 따라 선택하세요.

◆ ntn CLI — Notion의 공식 CLI. 더 짧은 구문, 한 줄 파일 업로드, Workers에 필요함. 2026년 5월 기준 macOS + Linux만 지원(Windows 지원 "곧 제공 예정"). 설치 시 기본값입니다. ◆ HTTP + curl — Windows를 포함한 모든 곳에서 작동합니다. ntn이 설치되지 않은 경우 기본 대체 방법입니다.

설정

1. 통합 토큰 얻기 (두 경로 모두 필요)

  1. https://notion.so/my-integrations 에서 통합을 만듭니다.
  2. API 키를 복사합니다(ntn_ 또는 secret_로 시작).
  3. ~/.hermes/.env에 저장합니다:
    NOTION_API_KEY=ntn_여기에_키_입력
    
  4. Notion에서 대상 페이지/데이터베이스를 통합과 공유합니다: 페이지 메뉴 ... → 연결 대상 → 통합 이름. 이 단계를 수행하지 않으면 API가 해당 페이지에 대해 404를 반환합니다(페이지가 존재함에도 불구하고).

2. ntn 설치 (macOS / Linux에서 선호)

# 권장
curl -fsSL https://ntn.dev | bash

# 또는 npm을 통해 (Node 22+, npm 10+ 필요)
npm install --global ntn

ntn --version    # 확인

ntn login은 건너뛰고 대신 통합 토큰을 사용하세요. 이렇게 하면 브라우저 없이 헤드리스로 작동합니다:

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn은 NOTION_API_TOKEN을 읽습니다
export NOTION_KEYRING=0                       # OS 키체인을 사용하지 않음

이 export를 셸 프로필(또는 ~/.hermes/.env)에 추가하여 모든 세션이 상속받도록 합니다.

3. 런타임에 경로 선택

if command -v ntn >/dev/null 2>&1; then
  # ntn 사용
else
  # curl로 대체
fi

Windows 사용자: 2단계를 완전히 건너뛰고 네이티브 ntn이 출시될 때까지 기다리세요 — 경로 B가 잘 작동합니다. 현재 CLI 편의성을 원한다면 WSL2 내에서 ntn을 설치하세요.

API 기본 사항

모든 HTTP 요청에는 Notion-Version: 2025-09-03이 필요합니다. ntn이 이를 자동으로 처리합니다. 이 버전에서 사용자들이 "데이터베이스"라고 부르는 것은 API에서 데이터 소스라고 합니다.

경로 A — ntn CLI (선호, macOS / Linux)

원시 API 호출 (curl의 단축 표기)

ntn api v1/users                                  # GET
ntn api v1/pages parent[page_id]=abc123 \         # 인라인 본문으로 POST
  properties[title][0][text][content]="노트"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH; :=는 문자열이 아님(불/숫자/null)

구문 참고:

  • key=value — 문자열 필드
  • key[nested]=value — 중첩 객체 필드
  • key:=value — 타입 할당 (불리언, 숫자, null, 배열)

검색

ntn api v1/search query="페이지 제목"

페이지 메타데이터 읽기

ntn api v1/pages/{page_id}

페이지를 마크다운으로 읽기 (에이전트 친화적)

ntn api v1/pages/{page_id}/markdown

페이지 콘텐츠를 블록으로 읽기

ntn api v1/blocks/{page_id}/children

마크다운에서 페이지 생성

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="회의 노트" \
  markdown="# 안건\n\n- Q3 로드맵\n- 채용"

마크다운으로 페이지 패치

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## 업데이트\n\n프로토타입을 출시했습니다."

데이터베이스(데이터 소스) 쿼리

ntn api v1/data_sources/{data_source_id}/query -X POST \
  filter[property]=상태 filter[select][equals]=활성

복잡한 쿼리(sorts, 여러 필터 절, 복합 논리 포함)의 경우 JSON을 파이프로 전달하세요:

echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
  ntn api v1/data_sources/{data_source_id}/query -X POST --json -

파일 업로드 (한 줄 명령어 — CLI의 가장 큰 장점)

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

3단계 HTTP 흐름(업로드 생성 → PUT 바이트 → 참조)과 비교하세요.

유용한 환경 변수

변수효과
NOTION_API_TOKEN인증 토큰(키체인 재정의) — 통합 토큰으로 설정
NOTION_KEYRING=0OS 키체인 대신 ~/.config/notion/auth.json에 파일 기반 자격 증명
NOTION_WORKSPACE_ID워크스페이스 선택기 프롬프트 건너뛰기

경로 B — HTTP + curl (크로스 플랫폼, Windows에서 기본값)

모든 요청은 다음 패턴을 공유합니다:

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

Windows 10+에 포함된 curl이 그대로 작동합니다. PowerShell 사용자는 Invoke-RestMethod를 사용할 수도 있습니다.

검색

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "페이지 제목"}'

페이지 메타데이터 읽기

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

페이지를 마크다운으로 읽기 (에이전트 친화적)

블록 JSON보다 모델에 제공하기 쉽습니다.

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

페이지 콘텐츠를 블록으로 읽기 (구조가 필요할 때)

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

마크다운에서 페이지 생성

POST /v1/pages는 markdown 본문 매개변수를 허용합니다.

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "properties": {"title": [{"text": {"content": "회의 노트"}}]},
    "markdown": "# 안건\n\n- Q3 로드맵\n- 채용\n\n## 결정 사항\n- MVP 금요일 출시"
  }'

마크다운으로 페이지 패치

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "## 업데이트\n\n프로토타입을 출시했습니다."}'

데이터베이스에 페이지 생성 (타입 속성 사용)

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "이름": {"title": [{"text": {"content": "새 항목"}}]},
      "상태": {"select": {"name": "할 일"}}
    }
  }'

데이터베이스(데이터 소스) 쿼리

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

데이터베이스 생성

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "내 데이터베이스"}}],
    "properties": {
      "이름": {"title": {}},
      "상태": {"select": {"options": [{"name": "할 일"}, {"name": "완료"}]}},
      "날짜": {"date": {}}
    }
  }'

페이지 속성 업데이트

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

페이지에 블록 추가

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hermes에서 보낸 인사!"}}]}}
    ]
  }'

파일 업로드 (3단계 흐름)

# 1. 업로드 생성
curl -s -X POST "https://api.notion.com/v1/file_uploads" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.png", "content_type": "image/png"}'

# 2. 위에서 반환된 upload_url에 PUT 바이트 전송
curl -s -X PUT "{upload_url}" --data-binary @photo.png

# 3. 페이지/블록 페이로드에서 {file_upload_id} 참조

속성 유형

데이터베이스 항목의 일반적인 속성 형식:

  • 제목: {"title": [{"text": {"content": "..."}}]}
  • 서식 있는 텍스트: {"rich_text": [{"text": {"content": "..."}}]}
  • 선택: {"select": {"name": "옵션"}}
  • 다중 선택: {"multi_select": [{"name": "A"}, {"name": "B"}]}
  • 날짜: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
  • 체크박스: {"checkbox": true}
  • 숫자: {"number": 42}
  • URL: {"url": "https://..."}
  • 이메일: {"email": "[email protected]"}
  • 관계: {"relation": [{"id": "page_id"}]}

API 버전 2025-09-03 — 데이터베이스 vs 데이터 소스

  • 데이터베이스가 데이터 소스가 되었습니다. 쿼리 및 검색에는 /data_sources/ 엔드포인트를 사용하세요.
  • 데이터베이스당 두 개의 ID: database_id 및 data_source_id.
    • 페이지 생성 시 database_id: parent: {"database_id": "..."}
    • 쿼리 시 data_source_id: POST /v1/data_sources/{id}/query
  • 검색은 데이터베이스를 data_source_id 필드와 함께 "object": "data_source"로 반환합니다.

Notion Workers (고급, ntn 필요)

Workers는 Notion이 호스팅하는 TypeScript 프로그램입니다. 하나의 Worker는 다음의 모든 조합을 노출할 수 있습니다:

  • 동기화 — 예약(기본 30분)에 따라 외부 API에서 Notion 데이터베이스로 데이터를 가져옵니다.
  • 도구 — Notion의 사용자 지정 에이전트 내에서 호출 가능한 도구로 나타납니다.
  • 웹훅 — 외부 서비스(GitHub, Stripe 등)로부터 HTTP 이벤트를 수신하여 Notion에서 작업을 수행합니다.

요금제 / 플랫폼 제한:

  • CLI는 모든 요금제에서 작동합니다. Workers 배포에는 Business 또는 Enterprise가 필요합니다.
  • ntn은 2026년 5월 기준 macOS/Linux 전용입니다. Windows 사용자는 WSL2가 필요하거나 네이티브 지원을 기다려야 합니다.
  • 2026년 8월 11일까지 무료이며, 이후에는 Notion 크레딧으로 측정 사용됩니다.

최소 Worker

ntn workers new my-worker      # 스캐폴드
cd my-worker
# Edit src/index.ts
ntn workers deploy --name my-worker

src/index.ts:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("greet", {
  title: "사용자에게 인사",
  description: "친근한 인사말을 반환합니다",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `안녕하세요, ${name}!`,
});

웹훅 기능

worker.webhook("onGithubPush", {
  title: "GitHub 푸시 핸들러",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody (서명 확인용), event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

배포 후: ntn workers webhooks list는 Notion이 생성한 URL을 보여줍니다. 해당 URL을 비밀로 취급하세요 — 서명 확인을 추가하지 않으면 URL을 가진 사람이 누구든 이벤트를 POST할 수 있습니다.

Worker 수명 주기 명령어

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # 지금 동기화 실행
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # 최근 호출
ntn workers runs logs <run-id>
ntn workers webhooks list

Worker를 빌드하라는 요청을 받으면 ntn workers new로 스캐폴드하고, src/index.ts에 코드를 작성하고, ntn workers env set으로 시크릿을 설정한 후 배포하세요. Notion 문서(https://developers.notion.com/workers)에서 전체 API 표면을 다룹니다.

Notion-Flavored Markdown (/markdown 엔드포인트에서 사용)

표준 CommonMark에 Notion 특정 블록을 위한 XML 유사 태그가 추가되었습니다. 들여쓰기에는 탭을 사용하세요.

CommonMark를 넘어서는 블록:

<callout icon="🎯" color="blue_bg">
	금요일까지 MVP를 출시하세요.
</callout>

<details color="gray">
<summary>토글 제목</summary>
	한 탭 들여쓰기된 자식 요소
</details>

<columns>
	<column>왼쪽</column>
	<column>오른쪽</column>
</columns>

<table_of_contents color="gray"/>

인라인:

  • 멘션: <mention-user url="..."/>, <mention-page url="...">제목</mention-page>, <mention-date start="2026-05-15"/>
  • 밑줄: <span underline="true">텍스트</span>
  • 색상: <span color="blue">텍스트</span> 또는 첫 번째 줄의 블록 수준 {color="blue"}
  • 수학: 인라인 $x^2$, 블록 $$ ... $$
  • 인용: [^https://example.com]

색상: gray brown orange yellow green blue purple pink red, 배경용 *_bg 변형.

제목 5/6은 H4로 축소됩니다. 여러 > 줄은 별도의 인용 블록으로 렌더링됩니다 — 여러 줄 인용을 위해서는 단일 > 안에서 <br>을 사용하세요.

올바른 경로 선택

작업mac / LinuxWindows
페이지 읽기/쓰기, 검색, 데이터베이스 쿼리ntn api ...curl
요약할 에이전트를 위해 페이지 읽기ntn api v1/pages/{id}/markdowncurl /markdown 엔드포인트
파일 업로드ntn files create < file3단계 HTTP 흐름
일회성 API 탐색ntn api ...curl
Notion이 호스팅하는 동기화/웹훅/에이전트 도구 빌드ntn workers ...WSL2 + ntn workers ...

참고 사항

  • 페이지/데이터베이스 ID는 UUID입니다(대시 포함 또는 미포함 — 둘 다 허용).
  • 속도 제한: 초당 약 3회 요청. CLI는 이를 우회하지 않습니다.
  • API는 데이터베이스 보기 필터를 설정할 수 없습니다 — UI 전용입니다.
  • 데이터 소스를 생성할 때 "is_inline": true를 사용하여 페이지에 임베드하세요.
  • 항상 -s를 curl에 전달하여 진행률 표시줄을 숨기세요(더 깔끔한 에이전트 출력).
  • 읽을 때는 JSON을 jq로 파이프하세요: ... | jq '.results[0].properties'.
  • Notion은 현재 MCP 서버도 제공합니다 (`Notion …

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a insurance agency. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generates a complete landing page with copy, layout, hero image, and responsive design from a text description. Use when launching a product quickly.

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a family law practice. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a fractional CFO firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a home remodeling company. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a HVAC service company. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a immigration law firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a CPA tax advisory firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a estate planning law firm. Use when handling...

Lord1Egypt/awesome-skill-forge

Fastest way to create or update a pawr.link profile. One curl command, $19 USDC to create, $0.10 to update. Patch-style update-links endpoint lets you add, remove, or move individual links without replacing the whole profile.

Lord1Egypt/awesome-skill-forge

Use this skill when the user wants to review today, look back on yesterday, reflect on this week, or wrap things up with a gentle, low-pressure reflection.

Lord1Egypt/awesome-skill-forge

Read-only queue dashboard for workspace-aware ship. (gstack)

Lord1Egypt/awesome-skill-forge

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says landing page, post-click experience, landing page audit, LP audit, conversion rate, landing page CRO, post-click CRO, or landing page optimization.

Lord1Egypt/awesome-skill-forge

Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants a rendered MP4/WebM from an HTML composition, wants to animate text/logos/charts over media, needs captions synced to audio, wants TTS narration, or wants to convert a website into a video.

Lord1Egypt/awesome-skill-forge

Search arXiv papers by keyword, author, category, or ID.

Lord1Egypt/awesome-skill-forge

Delegate coding to OpenAI Codex CLI (features, PRs).

Lord1Egypt/awesome-skill-forge

Track Apple devices/AirTags via FindMy.app on macOS.

Lord1Egypt/awesome-skill-forge

Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN.

Lord1Egypt/awesome-skill-forge

Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.

Lord1Egypt/awesome-skill-forge

p5.js sketches: gen art, shaders, interactive, 3D.

관련 스킬