better-notion-mcp

Servidor MCP de Notion priorizando Markdown con 9 herramientas compuestas, 39 acciones y ~77% de reducción de tokens mediante documentación por niveles.

GitHub

Prueba este MCPPatrocinado

Documentación

Better Notion MCP

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

Notion con Markdown primero para agentes de IA -- páginas, bases de datos, bloques y comentarios en una sola llamada.

Proyectos hermanos de n24q02m (clic para expandir)

Proyecto	Eslogan	Etiqueta
agent-chat-plugin	Agentes de IA pares chatean en una carpeta compartida — sin relevo humano, sin orquestador, tra...	Herramientas
better-code-review-graph	Grafo de conocimiento para revisiones de código eficientes en tokens -- búsqueda semántica y llam...	MCP
better-drive	Sincronización bidireccional de Google Drive con filtro .driveignore — motor rclone, bandeja de Windows	Herramientas
better-email-mcp	Correo IMAP/SMTP para agentes de IA -- leer, enviar, organizar carpetas y gestionar archivos adj...	MCP
better-godot-mcp	Servidor MCP compuesto para Godot Engine -- 17 herramientas compuestas para desarrollo asistido por IA...	MCP
better-notion-mcp	Notion con Markdown primero para agentes de IA -- páginas, bases de datos, bloques y comentarios...	MCP
better-semantic-release	Bifurcación directa de python-semantic-release con protecciones de seguridad de lanzamiento integradas (orp...	Herramientas
better-telegram-mcp	Telegram para agentes de IA -- mensajes, chats, medios y contactos en ambos bo...	MCP
better-workspace-mcp	Servidor MCP de Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Mercado de plugins de Claude Code para los servidores MCP de n24q02m -- instalar búsqueda web...	Mercado
imagine-mcp	Comprensión y generación de imágenes y videos para agentes de IA -- a través de Gemini, Op...	MCP
jules-task-archiver	Extensión de Chrome para operaciones masivas en tareas de Jules mediante la API batchexecute -- a...	Herramientas
mcp-core	Base compartida para construir servidores MCP -- transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memoria persistente de IA con búsqueda híbrida y sincronización integrada. Abierta, gratuita, ilimit...	MCP
qwen3-embed	Incrustación y reordenamiento de texto Qwen3 ligero mediante ONNX Runtime y GGUF	Biblioteca
skret	Secretos sin servidor.	CLI
tacet	Una cascada neuro-simbólica autodestilante que amortiza el costo de LLM en conocimiento...	Herramientas
web-core	Paquete de infraestructura web compartida para búsqueda, raspado, seguridad HTTP y almacenamiento...	Biblioteca
wet-mcp	Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y bibli...	MCP

Características

Markdown adentro, Markdown afuera -- contenido legible en lugar de bloques JSON crudos
8 herramientas compuestas, 39 acciones -- una llamada en lugar de encadenar 2+ endpoints atómicos de Notion (además de config, help y una herramienta de configuración de relevo)
Paginación automática y operaciones masivas -- sin manejo manual de cursores ni bucles
Optimización de tokens por niveles -- reducción de ~77% mediante descripciones comprimidas + herramienta help bajo demanda
Transporte dual -- stdio local (token de integración) o HTTP remoto (OAuth 2.1, sin token que pegar)

Instalación

Ejecuta con npx (Node.js >= 24) y un token de integración de Notion desde https://www.notion.so/my-integrations (comienza con 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" }
    }
  }
}

O ejecuta la imagen Docker publicada (stdio):

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

Consulta la sección Documentación para la configuración por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) y el modo HTTP/OAuth.

CLI

Instalar el paquete expone un binario better-notion-mcp (ejecútalo con npx o después de una instalación global). No tiene subcomandos -- ejecutarlo inicia el servidor MCP y habla el protocolo por stdin/stdout, por lo que normalmente lo lanza un cliente MCP en lugar de hacerlo 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	Efecto
(ninguno)	transporte stdio (predeterminado); requiere `NOTION_TOKEN`
`--http`	transporte HTTP con OAuth 2.1 (equivalente a `TRANSPORT_MODE=http` / `MCP_TRANSPORT=http`)

Consulta Configuración para la referencia completa de variables de entorno.

Remoto (modo HTTP)

Desplegado con el transporte HTTP, el servidor es un endpoint remoto protegido por OAuth 2.1 -- sin token de integración que pegar. Apunta un cliente MCP que admita servidores HTTP remotos al host donde lo desplegaste:

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

En la primera conexión, el cliente abre la pantalla de consentimiento OAuth de Notion; los tokens de acceso por usuario se mantienen solo en el proceso (consulta Modelo de confianza). Para levantar una instancia de este tipo, consulta Autoalojamiento (modo remoto) y Desplegar en Cloudflare.

Smithery

El repositorio incluye una configuración smithery.yaml para Smithery. Smithery lanza el servidor a través de stdio (npx -y @n24q02m/better-notion-mcp) y no requiere configuración en la instalación -- proporciona tus credenciales de Notion en tiempo de ejecución mediante el flujo de configuración propio del servidor (variable de entorno NOTION_TOKEN, o el formulario de relevo; consulta Configuración).

Estado

2026-05-02 -- Actualización de estabilización de arquitectura

Los últimos meses vieron una agitación significativa en torno al manejo de credenciales y el patrón de auto-inicio del puente demonio. Esto causó carreras entre procesos, spam de pestañas del navegador y una experiencia de configuración inconsistente entre plugins. La arquitectura ahora es estable: 2 modos limpios (stdio + HTTP), sin capa de puente demonio, sin auto-inicio desde stdio.

Disculpas por el período de inestabilidad. Si encontraste problemas con versiones anteriores, actualiza a la última versión y sigue la Guía de configuración actual -- la mayoría de los trucos anteriores ya no son necesarios.

Plugins relacionados del mismo autor:

wet-mcp -- Búsqueda web + extracción de contenido

mnemo-mcp -- Memoria persistente de IA

imagine-mcp -- Comprensión y generación de imágenes/videos

better-email-mcp -- Gestión de correo

better-telegram-mcp -- Telegram

better-godot-mcp -- Godot Engine

better-code-review-graph -- Grafo de conocimiento para revisión de código

Todos los plugins comparten la misma arquitectura -- instala una vez, el patrón se transfiere.

Documentación

Documentación completa en mcp.n24q02m.com/servers/better-notion-mcp/:

Configuración -- métodos de instalación para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Resumen de modos -- stdio (local, token de integración) y HTTP (remoto, OAuth 2.1)
Configuración multiusuario -- modelo de credenciales por JWT-sub (modo HTTP)

Instalar con agente de IA -- pega esto a tu agente de codificación de IA:

Instala el servidor MCP better-notion-mcp siguiendo los pasos en https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

Herramientas

Ocho herramientas compuestas de Notion (39 acciones) más tres herramientas de infraestructura (config, config__open_relay, help):

Herramienta	Acciones	Descripción
`pages`	`create`, `get`, `get_property`, `update`, `move`, `archive`, `restore`, `duplicate`	Crear, leer, actualizar y 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 bases de datos y gestión de páginas dentro de bases de datos
`blocks`	`get`, `children`, `append`, `update`, `delete`	Leer y manipular contenido de bloques
`users`	`list`, `get`, `me`, `from_workspace`	Listar y recuperar información de usuarios
`workspace`	`info`, `search`	Metadatos del espacio de trabajo y búsqueda entre espacios
`comments`	`list`, `get`, `create`	Comentarios de páginas y respuestas de discusión
`content_convert`	`markdown-to-blocks`, `blocks-to-markdown`	Convertir entre Markdown y bloques de Notion (usa un parámetro `direction`)
`file_uploads`	`create`, `send`, `complete`, `retrieve`, `list`	Subir archivos a Notion (de una o varias partes)
`config`	`status`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`	Inspeccionar y gestionar el estado de credenciales y el ciclo de vida de configuración
`config__open_relay`	-	Abrir el formulario de configuración de relevo en el navegador y devolver la URL de relevo + estado de credenciales
`help`	-	Obtener documentación completa para cualquier herramienta compuesta (parámetro `tool_name`)

Recursos MCP

URI	Descripción
`notion://docs/pages`	Referencia de operaciones de páginas
`notion://docs/databases`	Referencia de operaciones de bases de datos
`notion://docs/blocks`	Referencia de operaciones de bloques
`notion://docs/users`	Referencia de operaciones de usuarios
`notion://docs/workspace`	Referencia de operaciones del espacio de trabajo
`notion://docs/comments`	Referencia de operaciones de comentarios
`notion://docs/content_convert`	Referencia de conversión de contenido
`notion://docs/file_uploads`	Referencia de subida de archivos

Configuración

Variable	Requerida	Predeterminado	Descripción
`NOTION_TOKEN`	Sí (stdio)	-	Token de integración de Notion
`TRANSPORT_MODE` / `MCP_TRANSPORT`	No	`stdio`	Establece cualquiera a `http` para modo remoto (o pasa `--http`)
`PUBLIC_URL`	No (http)	-	URL pública del servidor para enlaces de redirección OAuth
`NOTION_OAUTH_CLIENT_ID`	Sí (http)	-	ID de cliente de integración pública de Notion (o bandera CLI `--oauth-client-id=<id>`, que anula la variable de entorno)
`NOTION_OAUTH_CLIENT_SECRET`	Sí (http)	-	Secreto de cliente de integración pública de Notion (o bandera CLI `--oauth-client-secret=<secret>`, que anula la variable de entorno)
`MCP_AUTH_DISABLE`	No (http)	-	Establecer a `1` para omitir la verificación de JWT Bearer cuando esté detrás de una puerta de enlace de autenticación externa
`PORT`	No	`0` (asignado por el SO)	Puerto del servidor; establece explícitamente (p. ej. `8080`) para fijar un puerto
`HOST`	No	-	Dirección de enlace (modo http)

Autoalojamiento (modo remoto)

Puedes autoalojar el servidor remoto con tu propia aplicación OAuth de Notion.

Requisitos previos:

Crea una Integración pública en https://www.notion.so/my-integrations
Establece la URI de redirección a https://your-domain.com/callback
Anota tu client_id y 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

Desplegar en Cloudflare

Ejecuta tu propio better-notion-mcp multiusuario sin servidor en Cloudflare (Worker + Container + KV). Requisitos previos: una cuenta de Cloudflare en el plan Workers de pago — necesario para Containers (el nivel gratuito de Cloudflare no incluye Containers) — y la CLI wrangler.

git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcp
wrangler login
Aprovisiona el namespace de KV y pega su id en wrangler.jsonc:
```
wrangler kv namespace create better-notion-kv
```
Configura los secretos:
```
wrangler secret put CREDENTIAL_SECRET
wrangler secret put NOTION_OAUTH_CLIENT_ID
wrangler secret put NOTION_OAUTH_CLIENT_SECRET
```
CREDENTIAL_SECRET es OBLIGATORIO: deriva una clave de firma OAuth determinista para que la identidad del usuario sobreviva a la recreación del contenedor.

Sube la imagen http al registro gestionado por CF y despliega:

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

Completa el flujo OAuth de Notion en el navegador en tu dominio de Worker.

Los tokens de acceso de Notion por usuario se cifran en KV (MCP_STORAGE_BACKEND=cf-kv), por lo que sobreviven al scale-to-zero. NO configures MCP_AUTH_DISABLE en un despliegue compartido/público: colapsa a todos los usuarios en un único bucket de tokens.

Comparación

Cómo se posiciona better-notion-mcp frente a sus competidores directos en cada pilar:

Capacidad	better-notion-mcp	makenotion/notion-mcp-server	suekou/mcp-notion-server	awkoy/notion-mcp-server
Markdown entrada/salida	Sí (ida y vuelta en páginas + bloques)	No (JSON crudo de Notion)	parcial (experimental, append + conversión opcional)	Sí (ida y vuelta + GFM)
Diseño de herramientas compuestas	Sí (8 herramientas compuestas, 39 acciones)	No (22 herramientas mapeadas a endpoints)	parcial (herramientas simplificadas + JSON crudo)	Sí (2 herramientas de despacho, 35+ operaciones)
Subida de archivos a Notion	Sí (`file_uploads`, una + varias partes)	No	No	Sí (`upload_file`, una + varias partes)
Comentarios	Sí (`comments`: list/get/create)	Sí	Sí	Sí
Transporte HTTP remoto + OAuth 2.1	Sí (multi-usuario por JWT-sub)	parcial (HTTP + token bearer, sin OAuth)	No (solo token stdio)	No (solo token stdio)
Autoalojable	Sí (Docker, app OAuth propia)	Sí	Sí	Sí
Licencia	Apache-2.0	?	MIT	MIT

Seguridad

OAuth 2.1 + PKCE S256 -- Autorización segura con code challenge
Límite de peticiones -- 120 req/min/IP en transporte HTTP
Vinculación del propietario de sesión -- comprobación de IP + TTL para vinculaciones de token pendientes
Seguridad ante null -- Maneja peculiaridades de la API de Notion (comments.list 404, rich_text indefinido)

Compilar desde el código fuente

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

Modelo de confianza

Este plugin implementa TC-NearZK (en memoria, efímero). Consulta la referencia del modelo de confianza para la clasificación completa.

Modo	Almacenamiento	Cifrado	¿Quién puede leer tus datos?
HTTP n24q02m-hosted (predeterminado)	En memoria `Map<sub, OAuthToken>`	Solo en proceso	Proceso del servidor (se borra al reiniciar)
HTTP autoalojado	Igual que el alojado	Igual	Solo tú (admin = usuario)
stdio (local)	`config.enc` en el directorio de configuración del SO (`%APPDATA%\mcp\Config\config.enc` en Windows, `~/.config/mcp/config.enc` en Linux/macOS)	AES-GCM, clave vinculada a la máquina	Solo tu usuario del SO

Licencia

Apache-2.0 -- Consulta LICENSE.