Claude Code + Notion: Fluxo de Trabalho Completo de Sistema de Conhecimento Automatizado

Obsidian vs Notion: Se você leu a versão do Obsidian deste guia, aqui está a principal diferença logo de cara. O Obsidian armazena arquivos Markdown simples — o Claude Code os lê diretamente, sem configuração. O Notion armazena tudo em um banco de dados proprietário — você precisa do MCP para conectá-los. Isso adiciona 15 minutos de configuração. O retorno é a sincronização em tempo real e a colaboração em equipe que o Obsidian não consegue igualar.

Por que conectá-los?

Quando você trabalha no Claude Code, seu espaço de trabalho do Notion é invisível. Toda vez que você precisa de contexto de uma especificação, uma nota de reunião ou uma página de projeto — você está copiando e colando entre as abas.

Com o Notion MCP conectado, o Claude Code pode:

• Pesquisar em todo o seu espaço de trabalho a partir do terminal
• Puxar um PRD ou especificação diretamente para uma sessão de codificação
• Criar e atualizar páginas sem sair do seu terminal
• Sincronizar documentos que você redigiu localmente para o Notion para revisão da equipe
• Consultar bancos de dados em inglês simples ("mostre-me todas as tarefas abertas com prazo esta semana")

O fluxo de trabalho se torna: redigir no Claude Code → enviar para o Notion quando você precisar de colaboração → puxar feedback de volta quando estiver pronto para continuar.

Sem copiar e colar. Sem confusão de versões. Os dois permanecem sincronizados.

Parte 1: Instale Tudo

Passo 1 — Instale o Claude Code

# macOS
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

# Linux
curl -fsSL https://claude.ai/install.sh | bash

# Verificar
claude doctor
claude auth login

Requisitos: Assinatura Claude Pro ($20/mês) ou Max.

⚠️ npm install -g @anthropic-ai/claude-code está obsoleto. Use o instalador nativo.

Passo 2 — Tenha uma Conta no Notion

Se você não tiver uma: notion.so. O plano gratuito funciona para uso pessoal. Para colaboração em equipe, você precisará do Plus ou superior.

Parte 2: Conectar o Notion ao Claude Code

Diferente do Obsidian (arquivos simples), o Notion requer uma conexão autenticada através do MCP. Dois métodos — escolha um.

Método A — Plugin Oficial (Recomendado, 5 minutos)

O Notion construiu e mantém um plugin oficial do Claude Code que instala tudo em um comando: servidor MCP + Skills + comandos de barra.

claude plugin add makenotion/claude-code-notion-plugin

Então autentique:

claude
> /mcp

Claude irá solicitar que você complete um fluxo OAuth no seu navegador. Faça login com sua conta do Notion, autorize o acesso, pronto.

Verifique a conexão:

> "Liste um título de página aleatório do meu espaço de trabalho do Notion"

Se retornar conteúdo real — você está conectado.

Método B — Configuração Manual do MCP (Mais Controle)

Adicione o servidor MCP hospedado do Notion diretamente:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Inicie uma sessão e complete o OAuth:

cd seu-projeto
claude

Claude irá detectar o servidor e solicitar autenticação na primeira utilização da ferramenta Notion.

Verifique:

claude mcp list
# Deve mostrar: notion  https://mcp.notion.com/mcp  conectado

Compartilhe com Sua Equipe

Adicione ao .mcp.json na raiz do seu projeto (comprometa isso):

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Cada membro da equipe autentica com sua própria conta do Notion. Claude respeita as permissões individuais — ele só pode acessar o que cada pessoa pode acessar.

⚠️ Importante: O Notion MCP usa OAuth — ele atua com suas permissões completas do Notion. Claude pode acessar tudo o que você pode acessar. Seja intencional sobre o que você pede para ele fazer.

Parte 3: O Que o Notion MCP Pode Realmente Fazer

Uma vez conectado, o Claude Code obtém estas ferramentas:

O servidor MCP hospedado do Notion converte tudo para Markdown antes de enviar para o Claude — otimizado para consumo de IA, não o formato de bloco JSON bruto da API original. Isso é importante: é significativamente mais eficiente em termos de tokens.

Parte 4: CLAUDE.md para Fluxos de Trabalho do Notion

Conte ao Claude sobre sua estrutura do Notion para que ele não precise adivinhar.

# Contexto do Projeto

## Estrutura do Espaço de Trabalho do Notion
- **Engenharia** — especificações técnicas, ADRs, runbooks
  - Banco de dados de especificações: [sua-url-do-banco-de-dados]
  - Banco de dados de ADR: [sua-url-do-banco-de-dados]
- **Produto** — PRDs, roadmap, pesquisa
  - Banco de dados de PRD: [sua-url-do-banco-de-dados]
- **Reuniões** — todas as notas de reunião, pesquisáveis por data e projeto
- **Tarefas** — quadro de sprint e backlog

## Convenções de Documentos
- PRDs têm propriedades: Status (Rascunho/Revisão/Aprovado), Proprietário, Sprint
- ADRs seguem o formato: Contexto → Decisão → Consequências
- Notas de reunião sempre incluem: Data, Participantes, Decisões, Itens de Ação

## O Que Claude Pode Fazer Aqui
- Pesquisar no Notion por contexto antes de iniciar qualquer implementação