Notion Sync

Publica e sincroniza conteúdo em bases do Notion diretamente do seu fluxo de trabalho com o Claude Code. Transforme notas, resumos de reuniões, rascunhos de artigos e tarefas em páginas estruturadas dentro de uma base de dados do Notion, sem sair do terminal.

O que faz

O Notion Sync conecta o agente à API oficial do Notion para automatizar a parte chata da documentação: criar páginas, preencher propriedades e manter tudo atualizado. Em vez de copiar e colar manualmente entre o seu editor e o navegador, você descreve o que quer publicar e o agente cuida do resto.

Casos de uso típicos:

• Transformar o resultado de uma conversa (decisões, próximos passos, links) em uma página de base de conhecimento.
• Publicar rascunhos de artigos de blog em uma base de conteúdo com status, autor e tags.
• Criar e atualizar tarefas em um quadro de projeto no Notion a partir de um pedido em linguagem natural.
• Sincronizar páginas existentes quando o conteúdo mudar, evitando duplicatas (busca por título antes de criar).
• Exportar relatórios curtos e fichas técnicas para uma base compartilhada com a equipe.

O plugin sempre respeita o esquema da sua base: ele consulta as propriedades disponíveis (Select, Multi-select, Status, Date, Rich text, Title) antes de escrever, evitando erros de tipo.

Instalação

Pelo marketplace do Claude Code:

/plugin marketplace add aulasdeia/plugins
/plugin install notion-sync

Ou instalando diretamente a partir do diretório local:

/plugin install ./library/plugins/notion-sync

Após instalar, reinicie a sessão do Claude Code para que os comandos /notion:* fiquem disponíveis.

Comandos disponíveis

• /notion:publish — Cria uma nova página em uma base do Notion a partir de um título/conteúdo descrito, preenchendo as propriedades adequadas.
• /notion:sync — Localiza uma página existente pelo título e atualiza o seu conteúdo e propriedades, em vez de duplicar.

Os comandos usam o subagente notion-publisher, especialista na API do Notion, para montar os blocos e propriedades corretos.

Configuração

Defina as variáveis de ambiente abaixo antes de usar o plugin. Use apenas os nomes — nunca cole o valor real do token em arquivos versionados.

• NOTION_TOKEN — Token de integração interna do Notion (Internal Integration Secret). Crie em https://www.notion.so/my-integrations e compartilhe a base com a integração.
• NOTION_DATABASE_ID — ID da base de dados padrão onde as páginas serão criadas/atualizadas. É o trecho de 32 caracteres na URL da base.

Exemplo de .env (sem valores reais):

NOTION_TOKEN=
NOTION_DATABASE_ID=

A integração precisa ter permissão de leitura e escrita sobre a base alvo. No Notion, abra a base, clique em ... → Conexões → adicione a sua integração.

Exemplo de uso

Publicar um resumo como página nova:

/notion:publish Resumo da reunião de produto de 16/06 — decisões e próximos passos

O agente vai:

1. Ler o esquema da base em NOTION_DATABASE_ID.
2. Definir a propriedade Title, preencher Status (ex.: "Rascunho"), Date (hoje) e Tags se existirem.
3. Converter o conteúdo em blocos (cabeçalhos, listas, parágrafos) e criar a página.
4. Devolver o link público/privado da página criada.

Atualizar uma página existente:

/notion:sync Resumo da reunião de produto de 16/06

O agente busca a página pelo título, mostra o que mudará e aplica a atualização apenas após sua confirmação.

Segurança e limites

• O NOTION_TOKEN concede acesso de escrita às bases compartilhadas com a integração. Trate-o como segredo: nunca o exponha em logs, commits ou capturas de tela.
• A API do Notion limita a ~3 requisições por segundo por integração. Para grandes volumes, o agente aplica espera entre chamadas.
• Cada bloco de texto tem limite de 2000 caracteres; conteúdos longos são divididos automaticamente em vários blocos.
• O comando /notion:sync sempre pede confirmação antes de sobrescrever conteúdo existente, reduzindo o risco de perda de dados.
• O plugin só escreve nas bases explicitamente compartilhadas com a integração — ele não consegue acessar páginas privadas fora desse escopo.