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 использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "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 использует массив объектов серверов, а не map.

~/.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 — эффект x10

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

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills