Easy Notion MCP

npx easy-notion-mcp

Conteúdo: Comparação · Configuração · Perfis de CLI · Configuração · Por que markdown · Como funciona · Ferramentas · Recursos MCP · Tipos de bloco · Ida e volta · Bancos de dados · Livro de receitas · Segurança · Estabilidade · FAQ · Comunidade

Como o easy-notion-mcp se compara a outros servidores MCP do Notion?

Quantos tokens o easy-notion-mcp economiza?

Ler o conteúdo de uma página custa cerca de 6–7× menos tokens de resposta do que o servidor MCP oficial do Notion, porque o JSON bruto de blocos do Notion carrega metadados por bloco (IDs de bloco, carimbos de data/hora, objetos de autor) que um agente lendo por conteúdo nunca precisa. Tipicamente ~5–7×, variando de ~3× em páginas com muito código a ~15× em páginas ricas, com ≥94% do conteúdo da página preservado. Medido em comparação ao servidor oficial de JSON bruto; aproximadamente equivalente a outros servidores baseados em markdown.

A vantagem é a omissão de metadados, não a eficiência de codificação. Com informação igual, os dois formatos custam aproximadamente o mesmo (a proporção comum de representação intermediária é ~1.0–1.06× em formatos de página totalmente representados, e 1.32× em prosa típica), então a economia são os metadados por bloco (UUIDs de bloco, carimbos de data/hora, objetos de autor, wrappers de anotação) que o JSON bruto carrega e uma leitura de conteúdo nunca usa. Consultas de banco de dados mostram uma vantagem semelhante de ~7× com completude total de conteúdo.

Metodologia, resultados por classe e todas as ressalvas: .meta/research/token-bench-results-2026-06-13.md (re-executado via scripts/bench/lib/recompute-tiers.ts).

Como configuro o easy-notion-mcp?

Com token de API

Crie uma integração do Notion, copie o token, compartilhe suas páginas com ela.

Claude Code:

claude mcp add notion -s user \
  -e NOTION_TOKEN=ntn_your_integration_token \
  -- npx -y easy-notion-mcp

Isso registra o servidor na configuração de nível de usuário do seu Claude Code (-s user) e passa NOTION_TOKEN diretamente para o processo filho do MCP via -e. Seu ambiente de shell e rcfiles não são alterados — o token fica no arquivo de configuração do Claude Code, com escopo para este servidor, e não é visível para outros processos. Para definir uma página pai padrão para create_page, adicione -e NOTION_ROOT_PAGE_ID=<page-id> ao mesmo comando.

OpenClaw:

openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'

Em seguida, forneça o token por meio do ambiente do shell pai antes de iniciar o OpenClaw:

export NOTION_TOKEN=ntn_your_integration_token

Esta forma export é o fallback genérico para qualquer cliente MCP que herde o ambiente do shell pai. Ressalva: só persiste na sessão de shell atual, a menos que você a adicione ao seu rcfile de shell, o que tem suas próprias implicações de segurança — prefira a forma -e acima ao usar especificamente o Claude Code.

Claude Desktop / Cursor / Windsurf — adicione ao seu arquivo de configuração MCP:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

Locais dos arquivos de configuração: Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json

{
  "servers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

Perfis de CLI para acesso ao Notion com baixo contexto

Use o CLI easy-notion quando um agente precisar de acesso ao Notion sem carregar toda a superfície de ferramentas do MCP, ou quando você quiser integrações separadas do Notion para diferentes modos de permissão. Os perfis ficam em ~/.config/easy-notion-mcp/profiles.json por padrão e referenciam nomes de variáveis de ambiente, não tokens brutos.

export NOTION_WORK_READONLY=ntn_readonly_token
export NOTION_WORK_WRITE=ntn_readwrite_token

npx -y --package easy-notion-mcp easy-notion profile add work-ro \
  --token-env NOTION_WORK_READONLY \
  --mode readonly \
  --default

npx -y --package easy-notion-mcp easy-notion profile add work-rw \
  --token-env NOTION_WORK_WRITE \
  --mode readwrite \
  --root-page-id your_root_page_id

Comandos de leitura funcionam com perfis somente leitura:

npx -y --package easy-notion-mcp easy-notion --profile work-ro search "roadmap" --filter pages
npx -y --package easy-notion-mcp easy-notion --profile work-ro page read PAGE_ID --include-metadata
npx -y --package easy-notion-mcp easy-notion --profile work-ro content search-in-page PAGE_ID --query "launch" --within-toggle "Script"

Comandos de mutação exigem um perfil de leitura e escrita:

npx -y --package easy-notion-mcp easy-notion --profile work-rw content append PAGE_ID --markdown "## Update"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content update-toggle PAGE_ID --title "Script" --markdown-file ./script.md
npx -y --package easy-notion-mcp easy-notion --profile work-rw content archive-toggle PAGE_ID --title "Done"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content restore-toggle ARCHIVED_BLOCK_ID

Comandos destrutivos do CLI suportam --dry-run como uma verificação prévia somente leitura. Ele executa a mesma busca e validação de markdown quando possível, retorna campos planejados como would_delete_block_ids, would_update, would_archive ou would_restore, e não altera o Notion.

A habilidade leve para roteamento de agentes está publicada neste repositório em skills/easy-notion-cli/. Ela ensina agentes a preferir o CLI para acesso ao Notion baseado em perfil em vez de registrar vários servidores MCP.

Com OAuth

Token de API + stdio é o padrão de menor fricção. Se você estiver executando uma implantação compartilhada ou quiser acesso por usuário, o OAuth lida com a autenticação sem token para copiar e colar.

Inicie o servidor:

npx -p easy-notion-mcp easy-notion-mcp-http

Requer as variáveis de ambiente NOTION_OAUTH_CLIENT_ID e NOTION_OAUTH_CLIENT_SECRET. Veja Configuração de OAuth abaixo.

Claude Code:

claude mcp add notion --transport http http://localhost:3333/mcp

OpenClaw:

openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"

Claude Desktop:

Vá para Configurações → Conectores → Adicionar conector personalizado, insira http://localhost:3333/mcp.

Seu navegador abrirá a página de autorização do Notion. Escolha as páginas para compartilhar, clique em Permitir, pronto.

{
  "mcpServers": {
    "easy-notion-mcp": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token",
        "NOTION_ROOT_PAGE_ID": "your_root_page_id"
      }
    }
  }
}

Dify / n8n / FlowiseAI (plataformas baseadas em Docker):

Execute o servidor HTTP na sua máquina host:

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token \
  NOTION_MCP_BIND_HOST=0.0.0.0 \
  NOTION_MCP_BEARER=$NOTION_MCP_BEARER \
  npx -p easy-notion-mcp easy-notion-mcp-http

Nas configurações do servidor MCP da sua plataforma, use host.docker.internal em vez de localhost, e adicione o bearer aos cabeçalhos das requisições:

http://host.docker.internal:3333/mcp
Authorization: Bearer <your NOTION_MCP_BEARER value>

Por que não localhost? Essas plataformas normalmente rodam em Docker. localhost dentro de um contêiner refere-se ao próprio contêiner, não à sua máquina host. host.docker.internal preenche essa lacuna.

Host e bearer HTTP: O servidor HTTP vincula 127.0.0.1 por padrão e o modo de token estático exige NOTION_MCP_BEARER. host.docker.internal alcança o IP de ponte do host, então defina NOTION_MCP_BIND_HOST=0.0.0.0 no host e envie o cabeçalho bearer em cada requisição do cliente. O modo OAuth, que emite bearers por usuário, é a alternativa para implantações Docker compartilhadas.

O easy-notion-mcp funciona com qualquer cliente compatível com MCP. O servidor roda via stdio (modo token de API) ou HTTP (modo OAuth ou token de API).

Se você tiver dúvidas durante a configuração, a comunidade no Discord é um bom lugar para perguntar. O canal #easy-notion-mcp cobre discussões de configuração e design. Bugs vão para issues no GitHub.

Configuração

Modo Stdio (token de API)

Sobre arquivos .env (apenas contribuidores): o easy-notion-mcp carrega um arquivo .env do diretório de trabalho atual via dotenv. Na prática, isso significa que .env só "funciona" quando você executa o servidor a partir de um checkout clonado do repositório (node dist/index.js após npm install && npm run build), porque a raiz do repositório é o seu cwd. Ele não é carregado quando o pacote é invocado via npx easy-notion-mcp ou uma instalação global de um diretório arbitrário — esse é o comportamento padrão do CLI do npm. Para o caminho npx, passe NOTION_TOKEN via a flag -e na configuração do Claude Code acima, ou via o bloco env da configuração do seu cliente MCP.

Transporte OAuth / HTTP

Execute npx -p easy-notion-mcp easy-notion-mcp-http para iniciar o servidor HTTP com suporte a OAuth.

Para obter credenciais OAuth, crie uma integração pública em notion.so/profile/integrations e configure http://localhost:3333/callback como a URI de redirecionamento.

No modo OAuth, create_page funciona sem NOTION_ROOT_PAGE_ID — as páginas são criadas na seção privada do espaço de trabalho do usuário por padrão.

Postura de segurança do modo HTTP

O transporte HTTP é projetado para redes confiáveis: auto-hospedagem de operador único com um segredo bearer, ou OAuth para implantações compartilhadas. Ele não é endurecido para exposição direta à internet aberta; coloque um proxy reverso com TLS na frente dele se precisar de acesso remoto.

O modo de token estático exige um bearer. Iniciar npx -p easy-notion-mcp easy-notion-mcp-http com apenas NOTION_TOKEN definido se recusará a iniciar. Defina um bearer de segredo compartilhado no ambiente do servidor e configure seu cliente MCP para enviá-lo como Authorization: Bearer <secret> em cada requisição /mcp:

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx -p easy-notion-mcp easy-notion-mcp-http

O bearer é comparado com crypto.timingSafeEqual. Bearers ausentes ou incorretos recebem 401 { "error": "invalid_token" }. Gire o segredo reiniciando o servidor com um novo valor.

A vinculação padrão é loopback. O servidor vincula 127.0.0.1 por padrão — apenas processos locais. Defina NOTION_MCP_BIND_HOST=0.0.0.0 para expor todas as interfaces, ou um IP específico como 192.168.1.5 para expor uma. O bearer é obrigatório independentemente da vinculação. Bearer-always é o limite de confiança. A proteção contra DNS-rebinding não está ativada no endpoint /mcp, e o CORS nos endpoints de registro/token OAuth (/register, /token, /revoke) é permissivo. Trate o bearer, ou o bearer por usuário do OAuth, como a única coisa entre a rede e seu workspace do Notion. Mantenha-o configurado mesmo para implantações somente em loopback. Se você precisar expor este servidor além de uma rede confiável, coloque-o atrás de um proxy reverso que lide com TLS e verificações de origem.

Modo OAuth para multi-usuário / remoto. O OAuth tem sua própria aplicação de bearer por usuário; NOTION_MCP_BEARER não é necessário no modo OAuth. Para implantações compartilhadas, o modelo de identidade por usuário do OAuth é o formato certo — token estático + bearer é destinado a auto-hospedagem de operador único.

Uploads de file:// são somente stdio. Markdown passado para create_page, append_content, replace_content, update_section, ou update_page.cover com URLs file:// é rejeitado via HTTP. Use o modo stdio para fluxos de trabalho com arquivos locais (create_page_from_file também é somente stdio), ou hospede o arquivo em uma URL HTTPS e use essa URL no markdown.

Por que markdown-first?

O pacote npm oficial do Notion MCP retorna JSON bruto da API — objetos de bloco profundamente aninhados com ~120 tokens de metadados por bloco. Outros servidores convertem para markdown, mas suportam apenas um punhado de tipos de bloco, descartando silenciosamente callouts, toggles, tabelas, equações e muito mais.

easy-notion-mcp usa markdown GFM padrão que os agentes já conhecem. Não há nada novo para aprender, nenhuma sintaxe de tag personalizada, nenhum objeto de bloco para construir. O agente escreve markdown, easy-notion-mcp lida com a conversão para a API de blocos do Notion — e de volta, com 24 tipos de bloco preservados.

Isso significa que os agentes podem editar conteúdo existente. Leia uma página, receba o markdown de volta, modifique a string, escreva de volta. Formatação e estrutura suportadas são preservadas para os tipos de bloco que este servidor representa, e as omissões e degradações conhecidas estão documentadas abaixo. Agentes editam páginas do Notion da mesma forma que editam código, como texto.

Como o easy-notion-mcp funciona?

Páginas — escreva e leia markdown:

create_page({
  title: "Sprint Review",
  markdown: "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only"
})

Leia de volta — o mesmo markdown sai:

read_page({ page_id: "..." })

{ "markdown": "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only" }

Modifique a string, chame replace_content, pronto. Ou mire em uma única seção pelo nome do cabeçalho com update_section. Ou faça um find_replace cirúrgico sem tocar no resto da página. Páginas também podem ter ícones emoji e imagens de capa definidos via create_page ou update_page.

Bancos de dados — escreva pares simples de chave-valor:

add_database_entry({
  database_id: "...",
  properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})

Sem objetos de tipo de propriedade, sem wrappers { select: { name: "Done" } } aninhados. easy-notion-mcp busca o esquema do banco de dados em tempo de execução e converte automaticamente. Agentes passam { "Status": "Done" }, easy-notion-mcp faz o resto.

Erros dizem como corrigi-los. Um nome de cabeçalho errado retorna os cabeçalhos disponíveis. Uma página ausente sugere compartilhá-la com a integração. Um filtro ruim diz para chamar get_database primeiro. Agentes podem se autocorrigir sem pedir ajuda ao usuário.

Conteúdo complexo funciona. Toggles aninhados dentro de toggles, colunas com tipos de conteúdo mistos (listas + blocos de código + blockquotes), aninhamento profundo de listas e unicode completo (japonês, chinês, árabe, emoji) são cobertos por testes de ida e volta. A busca por cabeçalho update_section não diferencia maiúsculas de minúsculas e retorna os cabeçalhos disponíveis em caso de erro. add_database_entries lida com falhas parciais, e entradas bem-sucedidas e com falha são retornadas separadamente para que os agentes possam tentar novamente apenas as falhas.

Quais ferramentas o easy-notion-mcp fornece?

easy-notion-mcp inclui 43 ferramentas com nomes individuais em 7 categorias (42 via HTTP, o que exclui o create_page_from_file somente stdio). As descrições das ferramentas mantêm o comportamento crítico de segurança inline e apontam para recursos MCP para material de referência mais longo, como sintaxe de markdown, formatos de aviso, paginação de propriedades e exemplos de update_data_source.

Páginas (20 ferramentas)

Ferramentas destrutivas suportam dry_run: true como pré-verificação. O dry-run não envia nem valida uploads locais de markdown file:// porque isso criaria uploads no Notion; use URLs HTTPS ou execute sem dry-run para arquivos locais. O dry-run de replace_content traduz markdown e retorna avisos do tradutor, mas não pode revelar campos unmatched_blocks ou truncated do lado do Notion porque não chama o endpoint de atualização do Notion.

restore_toggle é intencionalmente baseado em ID: passe o ID de bloco arquivado retornado por archive_toggle. O Notion não expõe enumeração de filhos arquivados para busca por título nem um fluxo de trabalho read_page include_archived, então restaurar-por-título não está disponível.

Navegação (3 ferramentas)

Cada linha de list_pages retorna id, title, created_time e last_edited_time, para que um agente possa distinguir páginas ativas de obsoletas sem uma ida e volta por página. Os carimbos de data/hora vêm direto do Notion, arredondados ao minuto, e last_edited_time avança em edições de conteúdo e propriedades da página. Observe a diferença deliberada de search, que retorna last_edited apenas como data, enquanto list_pages retorna last_edited_time como um carimbo de data/hora ISO-8601 completo.

Bancos de dados (9 ferramentas)

As ferramentas de escrita em banco de dados rejeitam nomes de propriedades desconhecidos e tipos de propriedades não suportados com um erro claro, em vez de descartá-los silenciosamente. Chame get_database primeiro para confirmar nomes e tipos de propriedades. Tipos de propriedades suportados para escrita: title, rich_text, number, select, multi_select, date, checkbox, url, email, phone, status, relation, people. Para people, passe uma única string de ID de usuário ou um array de IDs de usuário. Tipos computados (formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by) são preenchidos pelo Notion e não podem ser definidos via API. Escritas de valor também são rejeitadas para files, verification, place, location e button. Para escritas de relação, passe uma única string de ID de página ("Projects": "page-id") ou um array ("Projects": ["id-a", "id-b"]); um array vazio limpa a relação.

easy-notion-mcp busca o esquema do banco de dados, mapeia valores para o formato de propriedade do Notion e lida com a conversão de tipos automaticamente quando agentes passam pares simples de chave-valor como { "Status": "Done" }. O esquema é armazenado em cache por 5 minutos para evitar chamadas redundantes à API durante operações em lote.

Visualizações (6 ferramentas)

Comentários (2 ferramentas)

Usuários (2 ferramentas)

Servidor (1 ferramenta)

get_config é a ferramenta para usar quando um erro de caminho de arquivo ou configuração deixa você sem saber o que fazer. create_page_from_file só aceita caminhos dentro da raiz do workspace, e quando um caminho cai fora dela, a rejeição agora nomeia a raiz resolvida. get_config permite ler essa raiz diretamente em vez de inferi-la. No modo HTTP, a raiz do workspace não se aplica, então os campos de caminho são nulos e o status é not_applicable; o servidor nunca relata caminhos do host para chamadores HTTP.

Quais recursos MCP estão disponíveis?

Clientes que suportam Recursos MCP podem ler estes documentos sob demanda sem carregar todo o material de referência em cada descrição de ferramenta:

Quais tipos de bloco o easy-notion-mcp suporta?

easy-notion-mcp suporta 24 tipos de bloco do Notion usando sintaxe de markdown padrão estendida com convenções para blocos específicos do Notion, como toggles, colunas e callouts. Agentes escrevem markdown familiar — easy-notion-mcp lida com a conversão de e para o formato de bloco do Notion.

Markdown padrão

Sintaxe específica do Notion

Quebras de linha e collapse_soft_wraps

Por padrão, uma única quebra de linha dentro de um parágrafo é gravada como está. Markdown com quebras de linha fixas (a convenção na maioria dos repositórios) chega ao Notion carregando essas quebras de linha. Esse padrão não mudou.

Toda ferramenta de escrita em markdown aceita um collapse_soft_wraps: true opcional, que aplica a semântica de quebra suave do CommonMark: uma única quebra de linha dentro de um parágrafo vira um espaço, então um arquivo com quebras fixas chega como parágrafos contínuos. Linhas em branco ainda separam blocos e blocos de código cercados por delimitadores não são alterados em ambos os modos.

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --collapse-soft-wraps

Não use isso ao reenviar conteúdo que você leu de volta do Notion, ou quebras de linha intencionais serão perdidas.

Quebras forçadas explícitas (uma barra invertida no final ou dois espaços no final) se comportam de forma idêntica, independentemente de a opção estar definida, mas diferem conforme o caminho de gravação:

Essa diferença é uma propriedade do caminho de importação, não do collapse_soft_wraps.

Título e duplicação do H1 inicial

create_page e create_page_from_file aceitam um strip_leading_h1: true opcional, que remove o H1 inicial do documento para que um arquivo que comece com o mesmo título que você passa como title não coloque esse título duas vezes na página. Isso se aplica apenas quando o primeiro bloco convertido de nível superior é um heading_1 simples (sem alternância) e o padrão é falso.

easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --strip-leading-h1

create_page, create_page_from_file, append_content, replace_content, update_section e update_toggle aceitam return_block_map: false para omitir block_map quando não for necessário; o padrão permanece verdadeiro e inalterado.

Posso ler e reescrever páginas com a formatação preservada?

Sim, para as convenções de markdown que este servidor representa. O suporte de ida e volta cobre 24 tipos de bloco. Omissões e degradações conhecidas estão documentadas, e muitas são relatadas com avisos explícitos.

read_page retorna as convenções de markdown que create_page aceita: títulos, listas, tabelas, destaques, alternâncias, colunas, equações e menções a páginas.

Quando uma página contém tipos de bloco do Notion que este servidor ainda não representa, como synced_block, child_database, child_page ou link_to_page, read_page inclui um campo warnings com o código omitted_block_types listando os IDs e tipos de bloco omitidos. Escrever esse markdown de volta por meio de replace_content excluiria esses blocos, então o aviso permite que agentes evitem reescritas inseguras. Para uma menção a página inline, use @[Title](notion-url), que é uma construção separada do tipo de bloco link_to_page.

As notas de reunião do Notion AI (e os blocos obsoletos transcription) são renderizadas como uma alternância sintética contendo o título, um carimbo de data/hora de gravação opcional e seções ## Summary / ## Notes; as transcrições são incluídas apenas com read_page include_transcript: true. Essas leituras de renderização emitem um aviso read_only_block_rendered para sinalizar que escrever o markdown de volta substitui o bloco de reunião nativo por blocos comuns.

Algumas degradações não são relatadas por um aviso. No caminho replace_content, marcadores e incorporações são gravados como URLs simples (estes avisam), enquanto blocos file, audio e video são reduzidos às suas URLs silenciosamente. Anotações de sublinhado e cor de texto não são representadas em markdown e são descartadas silenciosamente na leitura e na gravação.

easy-notion-mcp permite que agentes leiam uma página, modifiquem a string de markdown e a gravem de volta preservando formatação, estrutura e conteúdo suportados. Sem tradução de formato. Sem reconstrução de blocos. Agentes editam páginas do Notion da mesma forma que editam código, como texto.

Qual é a diferença entre find_replace e replace_content?

easy-notion-mcp fornece três estratégias de edição para diferentes casos de uso:

• replace_content — Substitui todo o conteúdo de uma página por novo markdown. Melhor para reescritas completas.
• update_section — Substitui uma única seção identificada pelo nome do título. Por padrão, o markdown de substituição inclui o título e substitui a seção inteira. Passe preserve_heading: true (ou CLI --preserve-heading) para manter o ID do bloco de título existente, texto, tipo, comentários e estado de alternância enquanto substitui destrutivamente apenas o corpo da seção.
• find_replace — Encontra e substitui texto específico em qualquer lugar da página, preservando todo o outro conteúdo e arquivos anexados. Melhor para edições cirúrgicas.

Passe dry_run: true nas ferramentas MCP, ou --dry-run na CLI, antes de edições destrutivas quando você quiser uma resposta de pré-verificação em vez de uma mutação.

Como o easy-notion-mcp lida com bancos de dados?

easy-notion-mcp fornece 9 ferramentas de banco de dados que abstraem o formato complexo de propriedades do Notion. Agentes passam pares simples de chave-valor como { "Status": "Done", "Priority": "High" }; easy-notion-mcp busca o esquema do banco de dados em tempo de execução, o armazena em cache por 5 minutos e converte para o formato de propriedades do Notion automaticamente.

easy-notion-mcp suporta criar e atualizar bancos de dados com esquemas tipados, consultar com filtros e classificações, e operações em lote via add_database_entries (várias linhas em uma única chamada).

Livro de receitas: receitas para seu próprio agente

Estas receitas apontam seu próprio agente para o Notion. O agente é dono da inteligência; easy-notion-mcp fornece tecido conjuntivo determinístico por meio das ferramentas MCP existentes, então as receitas são executadas sob demanda com zero segunda instalação. Elas são gratuitas e soberanas: seu próprio agente, seu próprio token, configuração de token de API sem OAuth e consultas de banco de dados no plano gratuito.

Estas etapas funcionam por meio das ferramentas MCP ou do conector claude.ai quando as ferramentas equivalentes estão habilitadas. A Receita 2 também funciona por meio da habilidade CLI easy-notion em skills/easy-notion-cli/; a Receita 1 precisa de create_database, consulta de bloco de origem com search_in_page e um filtro de deduplicação estruturado, e a superfície CLI atual não expõe esse fluxo de trabalho completo. Agentes do Claude Code podem usar a habilidade operacional em skills/notion-recipes/.

Receita 1: notas de reunião para itens de ação

Esta receita transforma uma página de notas de reunião ou notas coladas em linhas deduplicadas em um banco de dados de Itens de Ação. A sequência de ferramentas é create_database uma vez, depois por execução read_page quando a origem é uma página, search_in_page para resolver o ID do bloco de origem de cada item, query_database com um filtro exato Item Key para cada item candidato, add_database_entry ou add_database_entries para novas linhas e uma verificação final query_database.

O resultado ao vivo comprovado foi de 5 linhas de uma reunião de planejamento. Responsáveis e datas de vencimento ausentes foram armazenados no multi-seleção Flags, não em Source, e um filtro query_database de {"property":"Item Key","rich_text":{"equals":"38bbe876-242f-81f1-97b7-df935d050a24:38bbe876-242f-81c9-86c6-d9a792fc70b7"}} retornou exatamente 1 linha. Executar duas vezes sobre as mesmas notas manteve a contagem em 5 com zero duplicatas. Uma busca de texto livre pelo nome compartilhado da reunião retornou todas as linhas porque também varreu Source, então esta receita usa o filtro exato de Chave de Item para deduplicação.

Limite de segurança: a Receita 1 é segura para reexecução e idempotente porque Item Key armazena a identidade estável do Notion da linha de origem (<pageId>:<blockId>), não o texto da ação.

Copiar e colar para usuários do conector claude.ai, Receita 1

Use the enabled easy-notion or Notion connector tools to turn my meeting notes into an Action Items database.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Meeting notes page or pasted meeting notes: <MEETING_NOTES_PAGE_OR_TEXT>
- Parent page for the database, if a new database is needed: <PARENT_PAGE>
- Existing Action Items database, if one already exists: <DATABASE_NAME_OR_ID>

If an Action Items database does not already exist, create one with these properties:
- Name: title
- Item Key: rich_text
- Owner: rich_text
- Due: date
- Status: status
- Flags: multi_select
- Source: rich_text

Read the meeting notes or use the pasted notes. Extract only discrete action items. For each item, derive:
- Name: the action text
- Owner: the named assignee, or blank
- Due: the stated date as ISO YYYY-MM-DD, or blank
- Item Key: the source line's stable identity, formatted as <sourcePageId>:<sourceBlockId>
- Source: the meeting title plus date, with no flags stashed here
- Status: Not started
- Flags: add needs-owner if no owner, and needs-due if no due date

Resolve sourceBlockId with search_in_page. read_page returns markdown without block IDs. For a Notion-page source, call read_page to extract items, then for each item call search_in_page with a verbatim, distinctive substring of that item's original source line. Use the matches[].block_id whose text is that source line. If several blocks match, use a longer verbatim substring to isolate one block. For pasted notes, first save them as a Notion page with create_page, then proceed through search_in_page. Do not rely on block IDs from create_page, which returns only {id,title,url}. If one source line contains multiple distinct actions, append a stable ordinal suffix in source order, such as :1 or :2, to keep keys unique.

Before inserting each item, dedupe with an exact Item Key filter:
{"property":"Item Key","rich_text":{"equals":"<that item's key>"}}

If the query returns no results, insert the row with simple key-value properties. If it returns a result, skip that item. Do not dedupe with free-text database search, because text search also scans Source and can false-match every row from the same meeting.

After inserting, query the database and summarize the rows created and skipped.

Re-running is safe and idempotent because the exact Item Key filter uses the source line's stable Notion identity, not the action wording.

Receita 2: edição em lote, localizar e substituir, e reparo

Esta receita cobre duas superfícies onde um agente pode iterar além dos limites nativos do Notion: reparo de propriedades de banco de dados e localizar e substituir no corpo da página. Para reparo de banco de dados, a sequência é get_database, query_database por todas as linhas, construir um mapa de normalização, update_database_entry para linhas que precisam de correções e depois reconsultar. Para texto de página, a sequência é find_replace com dry_run: true, find_replace com replace_all: true e depois read_page para verificar.

O reparo de banco de dados ao vivo comprovado normalizou 4 linhas com valores mistos de Eng e engineering para uma opção consistente, deixando linhas não relacionadas inalteradas. A edição de página ao vivo comprovada substituiu 4 ocorrências em parágrafos e no corpo de um título. Ressalva: a correspondência de opções de seleção e status não diferencia maiúsculas de minúsculas, e as gravações se ajustam à capitalização da opção existente mais antiga. Se uma variante em minúsculas já existir, escrever uma versão capitalizada reutiliza a opção em minúsculas existente. Para forçar capitalização específica, renomeie a opção na interface do Notion em vez de escrever a nova capitalização.

Copiar e colar para usuários do conector claude.ai, Receita 2

Use the enabled easy-notion or Notion connector tools to repair Notion database rows or replace repeated text in a Notion page.

Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.

Inputs I will provide:
- Target database for property repair: <DATABASE_NAME_OR_ID>
- Property to normalize: <PROPERTY_NAME>
- Normalization map, for example {"Eng":"Engineering","engineering":"Engineering"}
- Target page for find-replace, if needed: <PAGE_NAME_OR_ID>
- Find text and replacement text, if needed: <FIND_TEXT> -> <REPLACE_TEXT>

For database property repair:
1. Get the database schema so you know the exact property names. If select or status options are missing from the schema, query live rows and read the current values from the results.
2. Query the database rows. If the database is large, page through all results in a loop.
3. Build or use the normalization map I provide.
4. For each row whose property value needs fixing, update that row with a simple key-value map such as {"<PROPERTY_NAME>":"<CANONICAL_VALUE>"}.
5. Re-query the database and summarize how many rows changed and which values remain.

Important caveat: select and status option matching is case-insensitive, and writes snap to the earliest-existing option's casing. If a lowercase variant already exists, writing a capitalized version may reuse the lowercase option. To force specific casing, I need to rename the option in Notion's UI.

For page-body find-replace:
1. Run a dry-run find-replace with replace_all enabled and report the match count before changing anything.
2. If the match count is expected, run find-replace with replace_all enabled.
3. Read the page afterward and verify the replacement.

E quanto a segurança e injeção de prompt?

easy-notion-mcp inclui duas camadas de segurança para implantações em produção:

Endurecimento contra injeção de prompt: Respostas de leitura em markdown (read_page, read_section, read_block e read_toggle) incluem um prefixo de aviso de conteúdo instruindo o agente a tratar dados do Notion como conteúdo, não instruções. search_in_page retorna trechos/texto brutos que devem ser tratados da mesma forma. Isso reduz o risco de o conteúdo da página direcionar o comportamento do agente; o comportamento final depende do modelo e do cliente. Defina NOTION_TRUST_CONTENT=true para desabilitar o aviso de markdown se você controlar o espaço de trabalho.

Sanitização de URL: javascript:, data: e outros protocolos de URL inseguros são removidos e renderizados como texto simples. Apenas http:, https: e mailto: são permitidos.

Estabilidade e versionamento

easy-notion-mcp segue Versionamento Semântico. A partir de 1.0.0, o contrato público está congelado e é apenas aditivo: nomes de ferramentas, esquemas de entrada de ferramentas, formatos de retorno de ferramentas, as convenções personalizadas de markdown e o vocabulário de códigos de aviso não mudarão de forma que quebre até um futuro lançamento 2.0. Mudanças aditivas (novas ferramentas, novos parâmetros opcionais, novos campos de resposta opcionais, novos códigos de aviso) não quebram e podem ser lançadas em versões menores.

Duas superfícies estão fora deste congelamento: o contrato de autenticação OAuth / HTTP é experimental e pode mudar enquanto sua postura de segurança amadurece, e a CLI easy-notion é pré-1.0 e ainda não está coberta. Veja o CHANGELOG para a declaração completa do contrato e o histórico por versão.

Perguntas frequentes

Como o easy-notion-mcp é diferente do servidor MCP oficial do Notion?

O pacote npm oficial do MCP do Notion (@notionhq/notion-mcp-server) é um proxy de API bruto que retorna JSON do Notion sem modificações, então ler uma página custa aproximadamente 6–7× mais tokens de resposta do que o markdown do easy-notion-mcp. easy-notion-mcp converte tudo para markdown GFM padrão que agentes já conhecem, suporta 24 tipos de bloco com ressalvas documentadas de ida e volta e inclui endurecimento contra injeção de prompt. O Notion também oferece um servidor MCP remoto hospedado separado (baseado em OAuth) que usa um formato de markdown personalizado baseado em tags HTML, enquanto easy-notion-mcp usa sintaxe de markdown padrão.

Com quais clientes MCP o easy-notion-mcp funciona?

easy-notion-mcp funciona com qualquer cliente compatível com MCP, incluindo Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf e OpenClaw. Ele suporta tanto transporte stdio (token de API) quanto transporte HTTP (OAuth). Consulte as instruções de configuração para configurações prontas para copiar e colar em cada cliente.

O easy-notion-mcp suporta upload de arquivos?

Sim. O easy-notion-mcp suporta upload de arquivos usando o protocolo file:/// na sintaxe Markdown. Envie imagens com ![alt](file:///path/to/image.png) e arquivos com [name](file:///path/to/file.pdf).

O easy-notion-mcp lida com conteúdo aninhado e complexo?

Sim. Alternadores aninhados dentro de alternadores, colunas com tipos de conteúdo mistos (listas, citações em bloco e blocos de código em colunas diferentes), listas com marcadores e numeradas aninhadas, e suporte completo a Unicode, incluindo japonês, chinês, russo, árabe e emojis, são cobertos por testes de ida e volta para esses formatos suportados.

O easy-notion-mcp lida com falhas parciais em operações em lote?

Sim. add_database_entries retorna matrizes separadas de succeeded e failed. Se uma entrada falhar na validação, as demais ainda serão criadas. Os agentes podem tentar novamente apenas as falhas sem reenviar o lote inteiro.

Comunidade

Há um Discord da comunidade em discord.gg/S8cghJSVBU. O canal #easy-notion-mcp cobre dúvidas de configuração e discussões de design, e o restante do servidor está aberto para demonstrações ou conversas gerais. Para bugs e solicitações concretas de recursos, issues no GitHub continuam sendo o canal oficial.

Contribuindo

Issues e PRs são bem-vindos no GitHub.

Licença

MIT