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

Documentación

notion

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

Notion con prioridad en Markdown 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 que 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 de juegos as...	MCP
better-notion-mcp	Notion con prioridad en Markdown 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 ambas cuent...	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: instala búsqueda web se...	Mercado
imagine-mcp	Comprensión y generación de imágenes y videos para agentes de IA: en 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, sin lími...	MCP
qwen3-embed	Incrustación y reordenamiento de texto Qwen3 ligero mediante ONNX Runtime y GGUF	Biblioteca
skret	Secretos sin el servidor.	CLI
tacet	Una cascada neuro-simbólica autodestiladora que amortiza el costo de LLM en conocim...	Herramientas
web-core	Paquete de infraestructura web compartida para búsqueda, raspado, seguridad HTTP y al...	Biblioteca
wet-mcp	Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y bib...	MCP

Características

Markdown de entrada, Markdown de salida: contenido legible para humanos en lugar de bloques JSON sin procesar
8 herramientas compuestas, 39 acciones: una sola llamada en lugar de encadenar 2 o más 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 y 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": {
    "notion": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/notion@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

El paquete es @n24q02m/notion (anteriormente @n24q02m/better-notion-mcp; el paquete antiguo recibe una versión final y luego se congela). El id del Registro MCP sigue siendo io.github.n24q02m/better-notion-mcp, y el comando heredado better-notion-mcp se mantiene como un alias de notion.

O ejecuta la imagen Docker publicada (stdio):

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

Matriz de instalación

Cliente	Instalación
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-notion-mcp@n24q02m-plugins` (stdio; solicita `NOTION_TOKEN`), o una entrada `mcpServers` en `.mcp.json` / configuración del cliente
Codex CLI	Bloque `[mcp_servers.notion]` en `~/.codex/config.toml` (stdio `command`/`args` o HTTP `type`/`url`)
OpenCode	Bloque `mcpServers` en `opencode.json`
Cursor / Windsurf / Gemini CLI / cualquier cliente MCP	JSON `mcpServers` en la configuración del cliente: la misma forma que el ejemplo anterior

Guías completas por cliente: mcp.n24q02m.com/servers/better-notion-mcp/setup/. 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 notion (además del alias heredado 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 a través de stdin/stdout, por lo que normalmente lo lanza un cliente MCP en lugar de ejecutarse manualmente.

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

# Start the remote HTTP server (OAuth 2.1) instead of stdio
npx --yes @n24q02m/notion@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)

Implementado 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 implementaste:

// MCP client config -- remote HTTP (OAuth 2.1)
{
  "mcpServers": {
    "notion": {
      "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).

Smithery

El repositorio incluye una configuración smithery.yaml para Smithery. Smithery lanza el servidor a través de stdio (npx -y @n24q02m/notion) y no requiere configuración en el momento de la instalación: proporciona tus credenciales de Notion en tiempo de ejecución mediante el flujo de configuración propio del servidor (env 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 cambios significativos en el manejo de credenciales y el patrón de auto-inicio del puente demonio. Esto causó condiciones de carrera 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 las soluciones alternativas anteriores ya no son necesarias.

Plugins relacionados del mismo autor:

wet: búsqueda web + extracción de contenido

mnemo: memoria persistente de IA

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

email: gestión de correo

telegram: Telegram

better-godot-mcp: Godot Engine

crg: grafo de conocimiento para revisión de código

Todos los plugins comparten la misma arquitectura: instala una vez, los patrones se transfieren.

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
Descripción general 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)

Instala con un agente de IA: pega esto a tu agente de codificación de IA:

Instala el servidor MCP notion 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 de trabajo
`comments`	`list`, `get`, `create`	Comentarios de página 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 (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 la 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 de cualquier herramienta compuesta (parámetro `tool_name`)

Recursos MCP

URI	Descripción
`notion://docs/pages`	Referencia de operaciones de página
`notion://docs/databases`	Referencia de operaciones de base de datos
`notion://docs/blocks`	Referencia de operaciones de bloques
`notion://docs/users`	Referencia de operaciones de usuario
`notion://docs/workspace`	Referencia de operaciones de 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	Requerido	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 la Integración Pública de Notion (o el flag CLI `--oauth-client-id=<id>`, que anula la variable de entorno)
`NOTION_OAUTH_CLIENT_SECRET`	Sí (http)	-	Secreto de cliente de la Integración Pública de Notion (o el flag CLI `--oauth-client-secret=<secret>`, que anula la variable de entorno)
`MCP_AUTH_DISABLE`	No (http)	-	Establece a `1` para omitir la verificación del JWT Bearer cuando hay una puerta de enlace de autenticación externa
`PORT`	No	`0` (asignado por el SO)	Puerto del servidor; establécelo 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/notion:latest

Docker Compose (loopback)

docker-compose.http.yml compila el objetivo de imagen http y lo publica solo en la interfaz loopback del host (127.0.0.1:8081), por lo que el servidor nunca es accesible directamente desde otras máquinas:

export NOTION_OAUTH_CLIENT_ID=your-client-id
export NOTION_OAUTH_CLIENT_SECRET=your-client-secret
export CREDENTIAL_SECRET=$(openssl rand -hex 32)
export PUBLIC_URL=https://your-domain.com
docker compose -f docker-compose.http.yml up

El servidor escucha en http://localhost:8081/mcp. Para exponerlo, coloca tu propio proxy inverso TLS frente al puerto loopback y establece PUBLIC_URL al origen público (la URI de redirección de Notion es <PUBLIC_URL>/callback). Establece CREDENTIAL_SECRET: deriva una clave de firma OAuth determinista, por lo que la identidad del usuario sobrevive a una recreación del contenedor.

Los tokens de acceso de Notion por usuario se mantienen solo en proceso y se borran al reiniciar. NO establezcas MCP_AUTH_DISABLE en una implementación compartida/pública: colapsa a todos los usuarios en un único bucket de tokens.

Las imágenes de lanzamiento se publican multi-arquitectura (amd64 + arm64) en Docker Hub (n24q02m/notion) y GHCR (ghcr.io/n24q02m/notion). No hay un endpoint HTTP alojado por n24q02m.

Comparación

Cómo se compara notion con competidores directos en cada pilar:

Capacidad	notion	makenotion/notion-mcp-server	suekou/mcp-notion-server	awkoy/notion-mcp-server
Markdown de 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)
Cargas de archivos a Notion	Sí (`file_uploads`, única + multiparte)	No	No	Sí (`upload_file`, única + multiparte)
Comentarios	Sí (`comments`: listar/obtener/crear)	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 desafío de código
Límite de tasa -- 120 req/min/IP en transporte HTTP
Vinculación del propietario de sesión -- Verificación de IP + TTL para enlaces de token pendientes
Seguridad ante nulos -- Maneja peculiaridades de la API de Notion (comentarios.list 404, rich_text indefinido)

Compilar desde el Código Fuente

git clone https://github.com/n24q02m/notion.git
cd notion
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 autoalojado	En memoria `Map<sub, OAuthToken>`	Solo en proceso	Proceso del servidor (borrado al reiniciar); el operador que lo ejecuta
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.