Notion MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Oficial – publicado pela Notion, rastreia sua API fielmente
Consultas de banco de dados com filtro/classificação — trate o Notion como um armazenamento estruturado
Gravações em nível de bloco – anexar, atualizar, arquivar blocos específicos, não páginas inteiras
Pesquisa de página em todo o espaço de trabalho (o que você compartilhou com a integração)

Demo ao vivo

Como fica na prática

notion.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Notion

Peça a um agente que analise seu PRD em busca de lacunas

👤 PMs, líderes de tecnologia ⏱ ~15 min intermediate

Quando usar: Você elaborou uma especificação e deseja uma leitura crítica antes de compartilhar com a engenharia.

Pré-requisitos

Noção de token de integração interna — notion.so/my-integrations → Nova integração → copiar segredo
Página compartilhada com a integração — Na página: ••• → Conexões → adicione sua integração

Fluxo

Busque o conteúdo da página

Leia a página do Notion em <URL>. Resuma em 5 tópicos o que esta especificação está propondo.✓ Copiado

→ Resumo preciso de 1 parágrafo – prova que o agente entendeu
Encontre áreas subespecificadas

Liste todos os lugares onde a especificação é vaga: casos de erro ausentes, comportamento de borda indefinido, propriedade pouco clara, nenhum plano de implementação, nenhuma métrica de sucesso.✓ Copiado

→ Lista de lacunas numeradas com referências de páginas
Rascunhos de perguntas para a revisão

Converta essas lacunas em 5 a 10 perguntas específicas que um engenheiro revisor faria. Anexe-as à página Notion como uma nova seção de 'Perguntas Abertas'.✓ Copiado

→ Bloco de perguntas adicionado à página

Resultado: Uma especificação mais restrita, além de uma seção de perguntas abertas que inicia as conversas certas antes da reunião de revisão.

Armadilhas

Agente alucina detalhes que não estão nas especificações — No prompt, insista: 'apenas sinalizar lacunas; não invente fatos; cite a seção onde cada lacuna ocorre'
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 com: linear

Auto-generate a daily standup page from Linear + GitHub

👤 Engineering managers, scrum masters ⏱ ~10 min intermediate

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

Pré-requisitos

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

Fluxo

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

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

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

→ Page URL returned

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

Armadilhas

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

Combine com: linear · github

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

👤 Ops leads, support managers ⏱ ~20 min intermediate

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

Pré-requisitos

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

Fluxo

Search the workspace

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

→ Ranked result list
Read the most relevant

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

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

→ Answer with citation or honest 'not in docs'

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

Armadilhas

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

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

Pré-requisitos

Linear MCP installed — See linear guide

Fluxo

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

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

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

→ Linear issue URLs returned

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

Armadilhas

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

Combine com: linear

Audit your Notion docs for staleness

👤 Docs leads, DevEx engineers ⏱ ~20 min intermediate

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

Pré-requisitos

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

Fluxo

List child pages with timestamps

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

→ Full inventory
Filter to stale pages

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

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

→ Pages updated with review banner

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

Armadilhas

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'

Combinações

Combine com outros MCPs para 10× de alavancagem

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

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

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

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
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

Custo e limites

O que custa rodar

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

Segurança

Permissões, segredos, alcance

Escopos mínimos: read_content

Armazenamento de credenciais: Internal integration secret in env var NOTION_API_KEY

Saída de dados: All calls to api.notion.com

Nunca conceda: update_content insert_content

Solução de problemas

Erros comuns e correções

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.

Alternativas

Notion vs. outros

Alternativa	Quando usar	Troca
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

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills