better-notion-mcp

ARQUIVADO EM 2026-09-13 — Este repositório não é mais mantido. Use a API oficial do Notion em vez deste servidor MCP. Instalações existentes continuam funcionando, mas não recebem atualizações ou suporte.

Better Notion MCP

mcp-name: io.github.n24q02m/better-notion-mcp

Notion com foco em Markdown para agentes de IA — páginas, bancos de dados, blocos e comentários em uma única chamada.

Projetos irmãos de n24q02m (clique para expandir)

Projeto	Tagline	Tag
agent-chat-plugin	Agentes de IA pares conversam em uma pasta compartilhada — sem intermediário humano, sem orquestrador, fun...	Ferramentas
better-code-review-graph	Grafo de conhecimento para revisões de código eficientes em tokens — busca semântica e chamadas de...	MCP
better-drive	Sincronização bidirecional do Google Drive com filtro .driveignore — mecanismo rclone, bandeja do Windows	Ferramentas
better-email-mcp	E-mail IMAP/SMTP para agentes de IA — ler, enviar, organizar pastas e gerenciar anex...	MCP
better-godot-mcp	Servidor MCP composto para Godot Engine — 17 ferramentas compostas para jogos assistidos por I...	MCP
better-notion-mcp	Notion com foco em Markdown para agentes de IA — páginas, bancos de dados, blocos e comentários...	MCP
better-semantic-release	Fork do python-semantic-release com proteções de segurança de release integradas (orp...)	Ferramentas
better-telegram-mcp	Telegram para agentes de IA — mensagens, chats, mídia e contatos em ambos os bo...	MCP
better-workspace-mcp	Servidor MCP do Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...)	MCP
claude-plugins	Marketplace de plugins do Claude Code para os servidores MCP da n24q02m — instale pesquisa we...	Marketplace
imagine-mcp	Compreensão e geração de imagem e vídeo para agentes de IA — entre Gemini, Op...	MCP
jules-task-archiver	Extensão do Chrome para operações em massa em tarefas do Jules via API batchexecute — a...	Ferramentas
mcp-core	Fundação compartilhada para construir servidores MCP — transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memória persistente de IA com busca híbrida e sincronização incorporada. Aberto, gratuito, ilimit...	MCP
qwen3-embed	Embedding e reclassificação de texto Qwen3 leve via ONNX Runtime e GGUF	Biblioteca
skret	Segredos sem o servidor.	CLI
tacet	Uma cascata neuro-simbólica autodestilante que amortiza o custo de LLM em conhecimento...	Ferramentas
web-core	Pacote de infraestrutura web compartilhada para busca, scraping, segurança HTTP e st...	Biblioteca
wet-mcp	Servidor MCP de código aberto para agentes de IA: busca web, extração de conteúdo e lib...	MCP

Sumário

• Recursos
• Instalação
• CLI
• Remoto (modo HTTP)
• Smithery
• Status
• Documentação
• Ferramentas
• Configuração
• Implantar no Cloudflare
• Comparação
• Segurança
• Compilar a partir do código-fonte
• Modelo de confiança
• Licença

Recursos

• Markdown entra, Markdown sai — conteúdo legível por humanos em vez de blocos JSON brutos
• 8 ferramentas compostas, 39 ações — uma única chamada em vez de encadear 2+ endpoints atômicos do Notion (além de config, help e uma ferramenta de configuração de relay)
• Paginação automática e operações em massa — sem manipulação manual de cursor ou loops
• Otimização de tokens em camadas — redução de ~77% via descrições compactadas + ferramenta help sob demanda
• Transporte duplo — stdio local (token de integração) ou HTTP remoto (OAuth 2.1, sem token para colar)

Instalação

Execute com npx (Node.js >= 24) e um token de integração do Notion de https://www.notion.so/my-integrations (começa com ntn_):

// MCP client config (e.g. .mcp.json / Claude Code / Cursor)
{
  "mcpServers": {
    "better-notion-mcp": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-notion-mcp@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

Ou execute a imagem Docker publicada (stdio):

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/better-notion-mcp:latest

Matriz de instalação

Cliente	Instalação
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-notion-mcp@n24q02m-plugins (stdio; solicita NOTION_TOKEN), ou uma entrada mcpServers em .mcp.json / configurações do cliente
Codex CLI	Bloco [mcp_servers.better-notion-mcp] em ~/.codex/config.toml (stdio command/args ou HTTP type/url)
OpenCode	Bloco mcpServers em opencode.json
Cursor / Windsurf / Gemini CLI / qualquer cliente MCP	JSON mcpServers na configuração do cliente — mesma estrutura do exemplo acima

Guias completos por cliente: mcp.n24q02m.com/servers/better-notion-mcp/setup/. Consulte a seção Documentação para configuração por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) e modo HTTP/OAuth.

CLI

Instalar o pacote expõe um binário better-notion-mcp (execute com npx ou após uma instalação global). Ele não tem subcomandos — executá-lo inicia o servidor MCP e fala o protocolo via stdin/stdout, portanto normalmente é iniciado por um cliente MCP em vez de manualmente.

# Start the stdio server (default transport; requires NOTION_TOKEN)
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/better-notion-mcp@latest

# Start the remote HTTP server (OAuth 2.1) instead of stdio
npx --yes @n24q02m/better-notion-mcp@latest --http

Argumento / env	Efeito
(nenhum)	Transporte stdio (padrão); requer NOTION_TOKEN
--http	Transporte HTTP com OAuth 2.1 (equivalente a TRANSPORT_MODE=http / MCP_TRANSPORT=http)

Consulte Configuração para a referência completa de variáveis de ambiente.

Remoto (modo HTTP)

Implantado com o transporte HTTP, o servidor é um endpoint remoto protegido por OAuth 2.1 — sem token de integração para colar. Aponte um cliente MCP que suporte servidores HTTP remotos para o host onde você o implantou:

// MCP client config -- remote HTTP (OAuth 2.1)
{
  "mcpServers": {
    "better-notion-mcp": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

Na primeira conexão, o cliente abre a tela de consentimento OAuth do Notion; os tokens de acesso por usuário são mantidos apenas em processo (consulte Modelo de confiança). Para montar essa instância, consulte Auto-hospedagem (modo remoto) e Implantar no Cloudflare.

Smithery

O repositório inclui uma configuração smithery.yaml para Smithery. O Smithery inicia o servidor via stdio (npx -y @n24q02m/better-notion-mcp) e não requer configuração na instalação — forneça suas credenciais do Notion em tempo de execução pelo fluxo de configuração do próprio servidor (env NOTION_TOKEN, ou o formulário de relay; consulte Configuração).

Status

2026-05-02 — Atualização de estabilização da arquitetura

Nos últimos meses houve mudanças significativas no tratamento de credenciais e no padrão de auto-inicialização do daemon-bridge. Isso causou corridas entre processos, spam de abas no navegador e experiência de configuração inconsistente entre plugins. A arquitetura agora está estável: 2 modos limpos (stdio + HTTP), sem camada de daemon-bridge, sem auto-inicialização via stdio.

Pedimos desculpas pelo período de instabilidade. Se você encontrou problemas com versões anteriores, atualize para a versão mais recente e siga o Guia de configuração atual — a maioria das soluções alternativas anteriores não é mais necessária.

Plugins relacionados do mesmo autor:

• wet-mcp — Busca web + extração de conteúdo
• mnemo-mcp — Memória persistente de IA
• imagine-mcp — Compreensão e geração de imagem/vídeo
• better-email-mcp — Gerenciamento de e-mail
• better-telegram-mcp — Telegram
• better-godot-mcp — Godot Engine
• better-code-review-graph — Grafo de conhecimento para revisão de código

Todos os plugins compartilham a mesma arquitetura — instale uma vez, o padrão se transfere.

Documentação

Documentação completa em mcp.n24q02m.com/servers/better-notion-mcp/:

• Configuração — métodos de instalação para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Visão geral dos modos — stdio (local, token de integração) e HTTP (remoto, OAuth 2.1)
• Configuração multiusuário — modelo de credenciais por JWT-sub (modo HTTP)

Instale com agente de IA — cole isto no seu agente de codificação de IA:

Instale o servidor MCP better-notion-mcp seguindo os passos em https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

Ferramentas

Oito ferramentas compostas do Notion (39 ações) mais três ferramentas de infraestrutura (config, config__open_relay, help):

Ferramenta	Ações	Descrição
pages	create, get, get_property, update, move, archive, restore, duplicate	Criar, ler, atualizar e organizar páginas
databases	create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates	CRUD de bancos de dados e gerenciamento de páginas dentro de bancos de dados
blocks	get, children, append, update, delete	Ler e manipular conteúdo de blocos
users	list, get, me, from_workspace	Listar e recuperar informações de usuários
workspace	info, search	Metadados do workspace e busca entre workspaces
comments	list, get, create	Comentários em páginas e respostas em discussões
content_convert	markdown-to-blocks, blocks-to-markdown	Converter entre Markdown e blocos do Notion (usa um parâmetro direction)
file_uploads	create, send, complete, retrieve, list	Enviar arquivos para o Notion (único ou múltiplas partes)
config	status, setup_status, setup_start, setup_reset, setup_complete, set, cache_clear	Inspecionar e gerenciar estado de credenciais e ciclo de vida de configuração
config__open_relay	-	Abrir o formulário de configuração do relay no navegador e retornar a URL do relay + estado de credenciais
help	-	Obter documentação completa para qualquer ferramenta composta (parâmetro tool_name)

Recursos MCP

URI	Descrição
notion://docs/pages	Referência de operações de páginas
notion://docs/databases	Referência de operações de bancos de dados
notion://docs/blocks	Referência de operações de blocos
notion://docs/users	Referência de operações de usuários
notion://docs/workspace	Referência de operações de workspace
notion://docs/comments	Referência de operações de comentários
notion://docs/content_convert	Referência de conversão de conteúdo
notion://docs/file_uploads	Referência de envio de arquivos

Configuração

Variável	Obrigatória	Padrão	Descrição
NOTION_TOKEN	Sim (stdio)	-	Token de integração do Notion
TRANSPORT_MODE / MCP_TRANSPORT	Não	stdio	Defina um deles como http para o modo remoto (ou passe --http)
PUBLIC_URL	Não (http)	-	URL pública do servidor para links de redirecionamento OAuth
NOTION_OAUTH_CLIENT_ID	Sim (http)	-	ID do cliente da Integração Pública do Notion (ou flag CLI --oauth-client-id=<id>, que substitui a variável de ambiente)
NOTION_OAUTH_CLIENT_SECRET	Sim (http)	-	Segredo do cliente da Integração Pública do Notion (ou flag CLI --oauth-client-secret=<secret>, que substitui a variável de ambiente)
MCP_AUTH_DISABLE	Não (http)	-	Defina como 1 para pular a verificação do Bearer JWT ao usar um gateway de autenticação externo
PORT	Não	0 (atribuído pelo SO)	Porta do servidor; defina explicitamente (ex.: 8080) para vincular uma porta fixa
HOST	Não	-	Endereço de bind (modo http)

Self-Hosting (Modo Remoto)

Você pode hospedar o servidor remoto com seu próprio aplicativo OAuth do Notion.

Pré-requisitos:

1. Crie uma Integração Pública em https://www.notion.so/my-integrations
2. Defina o URI de redirecionamento como https://your-domain.com/callback
3. Anote seu client_id e client_secret

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  -e NOTION_OAUTH_CLIENT_ID=your-client-id \
  -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
  n24q02m/better-notion-mcp:latest

Implantar no Cloudflare

Execute seu próprio better-notion-mcp multiusuário sem servidor no Cloudflare (Worker + Container + KV).

Implantação (gerenciada por CD)

Implantações gerenciadas passam pelo CI, nunca manualmente: o job deploy-cf em .github/workflows/cd.yml é executado após um release, faz checkout da tag lançada, constrói a imagem imutável http-slim na versão lançada, envia para o registry gerenciado do Cloudflare, implanta e depende de uma verificação canary — uma instância gerenciada só pode executar uma tag de release exata. wrangler deploy manual contra uma instância gerenciada/operada não é permitido: isso quebra a correspondência tag-de-release ↔ imagem-ao-vivo, e a próxima execução do CD a sobrescreveria.

O job é controlado pela variável de Actions do repositório CF_HOSTED_ENABLED — atualmente false, então releases não publicam um endpoint hospedado. Para executar sua própria instância, use os passos de self-host abaixo.

Pré-requisitos: uma conta Cloudflare no plano Workers Paid — necessário para Containers (o plano gratuito do Cloudflare não inclui Containers) — e o CLI wrangler.

1. git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcp
2. wrangler login
3. Provisione o namespace KV e cole o id em wrangler.jsonc:

   wrangler kv namespace create better-notion-kv
   

4. Defina os segredos:

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put NOTION_OAUTH_CLIENT_ID
   wrangler secret put NOTION_OAUTH_CLIENT_SECRET
   

   CREDENTIAL_SECRET é OBRIGATÓRIO: ele deriva uma chave de assinatura OAuth determinística para que a identidade do usuário sobreviva à recriação do container.
5. Envie a imagem http para o registry gerenciado do CF e implante:

   wrangler containers push better-notion-mcp:beta
   wrangler deploy
   

6. Complete o fluxo OAuth do Notion no navegador no domínio do seu Worker.

Os tokens de acesso do Notion por usuário são criptografados no KV (MCP_STORAGE_BACKEND=cf-kv), então sobrevivem ao scale-to-zero. NÃO defina MCP_AUTH_DISABLE em uma implantação compartilhada/pública — isso colapsa todos os usuários em um único bucket de tokens.

Comparação

Como o better-notion-mcp se compara aos concorrentes diretos em cada pilar:

Capacidade	better-notion-mcp	makenotion/notion-mcp-server	suekou/mcp-notion-server	awkoy/notion-mcp-server
Markdown entrada/saída	Sim (round-trip em páginas + blocos)	Não (JSON bruto do Notion)	parcial (experimental, append + conversão opt-in)	Sim (round-trip + GFM)
Design de ferramentas compostas	Sim (8 ferramentas compostas, 39 ações)	Não (22 ferramentas mapeadas a endpoints)	parcial (ferramentas simplificadas + JSON bruto)	Sim (2 ferramentas de despacho, 35+ operações)
Upload de arquivos para o Notion	Sim (file_uploads, única + múltiplas partes)	Não	Não	Sim (upload_file, única + múltiplas partes)
Comentários	Sim (comments: listar/obter/criar)	Sim	Sim	Sim
Transporte HTTP remoto + OAuth 2.1	Sim (multiusuário por JWT-sub)	parcial (HTTP + bearer token, sem OAuth)	Não (somente token stdio)	Não (somente token stdio)
Auto-hospedável	Sim (Docker, app OAuth próprio)	Sim	Sim	Sim
Licença	Apache-2.0	?	MIT	MIT

Segurança

• OAuth 2.1 + PKCE S256 — Autorização segura com code challenge
• Limite de taxa — 120 req/min/IP no transporte HTTP
• Vínculo do proprietário da sessão — Verificação de IP + TTL para binds de token pendentes
• Segurança contra nulos — Lida com peculiaridades da API do Notion (comments.list 404, rich_text indefinido)

Compilar a partir do Código-Fonte

git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
bun install
bun run dev

Modelo de Confiança

Este plugin implementa TC-NearZK (em memória, efêmero). Veja a referência do modelo de confiança para a classificação completa.

Modo	Armazenamento	Criptografia	Quem pode ler seus dados?
HTTP hospedado n24q02m (padrão)	Map<sub, OAuthToken> em memória	Somente no processo	Processo do servidor (limpo na reinicialização)
HTTP auto-hospedado	Igual ao hospedado	Igual	Somente você (admin = usuário)
stdio (local)	config.enc no diretório de configuração do SO (%APPDATA%\mcp\Config\config.enc no Windows, ~/.config/mcp/config.enc no Linux/macOS)	AES-GCM, chave vinculada à máquina	Somente seu usuário do SO

Licença

Apache-2.0 — Veja LICENSE.