Notion MCP — Use Cases, Install & Live Demo

Why use it

Key features

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)

Live Demo

What it looks like in practice

notion.replay ▶ ready

0/0

Install

Pick your client

~/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"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

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

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

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

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

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Notion

Have an agent review your PRD for gaps

👤 PMs, tech leads ⏱ ~15 min intermediate

When to use: You drafted a spec and want a critical read before sharing with engineering.

Prerequisites

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

Flow

Fetch the page content

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

→ 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.✓ Copied

→ 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.✓ Copied

→ Questions block added to the page

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

Pitfalls

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

Combine with: linear

Auto-generate a daily standup page from Linear + GitHub

👤 Engineering managers, scrum masters ⏱ ~10 min intermediate

When to use: You run a daily Notion standup page and want it pre-filled with yesterday's activity.

Prerequisites

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

Flow

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.✓ Copied

→ 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.✓ Copied

→ 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).✓ Copied

→ Page URL returned

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

Pitfalls

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

Combine with: linear · github

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

👤 Ops leads, support managers ⏱ ~20 min intermediate

When to use: New hires keep asking the same questions. Your answers are already written in Notion — just not findable.

Prerequisites

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

Flow

Search the workspace

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

→ Ranked result list
Read the most relevant

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

→ 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.✓ Copied

→ Answer with citation or honest 'not in docs'

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

Pitfalls

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

When to use: You took rough notes during a meeting in Notion. Now you need to extract the action items.

Prerequisites

Linear MCP installed — See linear guide

Flow

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'.✓ Copied

→ 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.✓ Copied

→ 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.✓ Copied

→ Linear issue URLs returned

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

Pitfalls

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

Combine with: linear

Audit your Notion docs for staleness

👤 Docs leads, DevEx engineers ⏱ ~20 min intermediate

When to use: Quarterly cleanup — find docs that haven't been touched in 6+ months and likely lie.

Prerequisites

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

Flow

List child pages with timestamps

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

→ Full inventory
Filter to stale pages

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

→ 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.'✓ Copied

→ Pages updated with review banner

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

Pitfalls

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'

Combinations

Pair with other MCPs for X10 leverage

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.✓ Copied

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.✓ Copied

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.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
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

Cost & Limits

What this costs to run

API quota: Notion: average 3 req/sec per integration, bursts allowed. Will 429 aggressively at scale.
Tokens per call: 500–3000 tokens per page depending on block count
Monetary: Free — API included with any Notion plan
Tip: Pages with many nested blocks are expensive to read fully. Search first, fetch only targeted pages.

Security

Permissions, secrets, blast radius

Minimum scopes: read_content

Credential storage: Internal integration secret in env var NOTION_API_KEY

Data egress: All calls to api.notion.com

Never grant: update_content insert_content

Troubleshooting

Common errors and fixes

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.

Alternatives

Notion vs others

Alternative	When to use it instead	Tradeoff
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

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills