Notion MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Official — published by Notion, tracks their API faithfully
Database queries with filter/sort — treat Notion like a structured store
Block-level writes — append, update, archive specific blocks not whole pages
Page search across the whole workspace (what you've shared with the integration)

라이브 데모

실제 사용 모습

notion.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "notion": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@notionhq/notion-mcp-server"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add notion -- npx -y @notionhq/notion-mcp-server

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Notion

Have an agent review your PRD for gaps

👤 PMs, tech leads ⏱ ~15 min intermediate

언제 쓸까: You drafted a spec and want a critical read before sharing with engineering.

사전 조건

Notion internal integration token — notion.so/my-integrations → New integration → copy secret
Page shared with the integration — On the page: ••• → Connections → add your integration

흐름

Fetch the page content

Read the Notion page at <URL>. Summarize in 5 bullets what this spec is proposing.✓ 복사됨

→ Accurate 1-paragraph summary — proves the agent understood it
Find underspecified areas

List every place where the spec is vague: missing error cases, undefined edge behavior, unclear ownership, no rollout plan, no success metric.✓ 복사됨

→ Numbered gap list with page references
Draft questions for the review

Convert those gaps into 5-10 specific questions a reviewing engineer would ask. Append them to the Notion page as a new 'Open Questions' section.✓ 복사됨

→ Questions block added to the page

결과: A tighter spec plus an Open Questions section that gets the right conversations started before the review meeting.

함정

Agent hallucinates details that aren't in the spec — In the prompt, insist: 'only flag gaps; do not invent facts; cite the section where each gap occurs'
Long specs get truncated on fetch — Use retrieve_block_children page-by-page if the page has many blocks; don't rely on a single get_page call

함께 쓰기: linear

Auto-generate a daily standup page from Linear + GitHub

👤 Engineering managers, scrum masters ⏱ ~10 min intermediate

언제 쓸까: You run a daily Notion standup page and want it pre-filled with yesterday's activity.

사전 조건

A Notion 'Standups' database — Has properties: Date (date), Team (select), Status (rich_text)

흐름

Gather yesterday's activity

From Linear, list issues moved to Done in the last 24h for ENG team. From GitHub, list merged PRs by our team.✓ 복사됨

→ Combined activity list
Build the standup content

Format as: Wins (shipped), In-flight (open PRs), Blockers (issues tagged 'blocked'), Today's focus (issues in-progress). Keep each section under 5 bullets.✓ 복사됨

→ Formatted block list
Create the Notion page

Create a new page in the Standups database. Date = today, Team = ENG, and paste the content as structured blocks (h2 per section).✓ 복사됨

→ Page URL returned

결과: A pre-filled standup page ready for the 9am sync, saves 15 minutes of scrambling.

함정

Database property names are case-sensitive and must match exactly — List properties with retrieve_database before first run and hardcode the exact keys

함께 쓰기: linear · github

Build a Slack-ready Q&A bot over your Notion docs

👤 Ops leads, support managers ⏱ ~20 min intermediate

언제 쓸까: New hires keep asking the same questions. Your answers are already written in Notion — just not findable.

사전 조건

Onboarding docs live in a known Notion space — Share the parent page with the integration so all children inherit access

흐름

Search the workspace

Search Notion for pages matching: '[user question]'. Return top 5 page titles and URLs.✓ 복사됨

→ Ranked result list
Read the most relevant

For the top 2 matches, fetch full content. Quote the passages that answer the question.✓ 복사됨

→ Verbatim quotes + source URLs
Answer with citations

Answer the user's question in 2-3 sentences, grounded only in those quotes. End with: 'Source: <url>'. If the docs don't actually answer, say so.✓ 복사됨

→ Answer with citation or honest 'not in docs'

결과: Grounded answers that let people find their own way to the source doc — no more 'where is X?' in Slack.

함정

Agent fabricates a plausible answer when docs don't actually cover it — Explicit instruction: 'if the retrieved quotes don't answer the question, reply with I don't see this in our docs — no guesses'
Notion search is keyword-based, misses semantic matches — If results feel thin, pair with a proper RAG stack (embed Notion content into a vector DB)

Convert meeting notes into Linear issues

👤 Tech leads, PMs ⏱ ~10 min beginner

언제 쓸까: You took rough notes during a meeting in Notion. Now you need to extract the action items.

사전 조건

Linear MCP installed — See linear guide

흐름

Read the meeting page

Read the Notion page at <URL>. Extract every action item — anything phrased as 'X will do Y' or 'we should Z'.✓ 복사됨

→ List with owner if mentioned
Confirm before creating

Show me the action list. For each, propose a Linear title, team, and priority. Do not create yet.✓ 복사됨

→ Dry-run table for human review
Create approved items

Create Linear issues for items 1, 3, and 5. Link each back to the Notion meeting page.✓ 복사됨

→ Linear issue URLs returned

결과: Meeting actions that actually get tracked instead of lost in a Notion page no one revisits.

함정

Agent treats every informational bullet as an action — In the prompt: 'only items with a clear owner OR a deliverable — drop everything else'

함께 쓰기: linear

Audit your Notion docs for staleness

👤 Docs leads, DevEx engineers ⏱ ~20 min intermediate

언제 쓸까: Quarterly cleanup — find docs that haven't been touched in 6+ months and likely lie.

사전 조건

A root page for the docs area — e.g., /Engineering/Docs — shared with the integration

흐름

List child pages with timestamps

List all descendant pages under the 'Engineering Docs' page. For each: title, URL, last_edited_time, last_edited_by.✓ 복사됨

→ Full inventory
Filter to stale pages

Filter to pages last edited more than 180 days ago. Group by top-level section.✓ 복사됨

→ Stale list per section
Tag for review

For each stale page, add a callout block at the top: '⚠ Needs review — last updated <date>. Ping <last-editor> to confirm.'✓ 복사됨

→ Pages updated with review banner

결과: A docs area where staleness is visible, not hidden — and owners get a nudge to either update or delete.

함정

Some pages are deliberately archival (ADRs, postmortems) and should NOT get the banner — Filter by tag or parent — exclude anything under /Archive or tagged 'historical'

조합

다른 MCP와 조합해 10배 효율

notion + linear

Scaffold a Linear project from a Notion PRD

Read the Notion PRD at <URL>, extract deliverables, and create a matching Linear project with issues grouped by milestone.✓ 복사됨

notion + github

Keep a README in sync with a Notion design doc

Read the Notion page '<API Design>' and update the README.md in our api repo to match — open a PR with the diff.✓ 복사됨

notion + sentry

Post weekly engineering quality reports to a Notion database

Pull this week's Sentry error stats per project and create a new page in the Notion 'Weekly Quality' database.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
search	query, filter?: {property, value}	Discovery — find pages by keyword across the workspace	1 API call
retrieve_page	page_id	Get page metadata/properties — not content blocks	1 API call
retrieve_block_children	block_id, start_cursor?	Read actual page content — call repeatedly until no next_cursor	1 API call (may need pagination)
append_block_children	block_id, children: Block[]	Add content to a page or under a specific block	1 API call
update_block	block_id, {type}: {...}	Edit text/content of an existing block in place	1 API call
create_page	parent: {database_id}\|{page_id}, properties, children?	Create a new page — under a parent page or inside a database	1 API call
query_database	database_id, filter?, sorts?	Structured query — filter/sort entries in a database	1 API call
update_page	page_id, properties	Update page-level properties (status, tags, date)	1 API call
retrieve_database	database_id	Introspect property names/types before writing	1 API call

비용 및 제한

운영 비용

API 쿼터: Notion: average 3 req/sec per integration, bursts allowed. Will 429 aggressively at scale.
호출당 토큰: 500–3000 tokens per page depending on block count
금액: Free — API included with any Notion plan
팁: Pages with many nested blocks are expensive to read fully. Search first, fetch only targeted pages.

보안

권한, 시크릿, 파급범위

최소 스코프: read_content

자격 증명 저장: Internal integration secret in env var NOTION_API_KEY

데이터 외부 송신: All calls to api.notion.com

절대 부여 금지: update_content insert_content

문제 해결

자주 발생하는 오류와 해결

object_not_found

Page exists but isn't shared with your integration. Open the page → ••• → Connections → add integration.

validation_error on create_page

Property names/types in your payload don't match the database schema. Call retrieve_database first and copy exact keys.

429 rate limited

Notion limits to ~3 req/sec. Add a 350ms sleep between writes or batch via append_block_children (send 100 blocks per call, not 100 calls).

Page content looks empty

retrieve_page returns metadata only — content is in blocks. Call retrieve_block_children to get actual text.

대안

Notion 다른 것과 비교

대안	언제 쓰나	단점/장점
Confluence MCP	Your org is on Confluence/Atlassian instead of Notion	Heavier permissions model; agent workflows tend to be slower
Obsidian / filesystem MCP	Your knowledge base is local markdown files	No multi-user sync or permissions, but zero API cost and instant reads

Notion

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Notion

사전 조건

흐름

함정

사전 조건

흐름

함정

사전 조건

흐름

함정

사전 조건

흐름

함정

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Notion 다른 것과 비교

더 보기

리소스