Notion MCP

Servidor MCP de Notion

[!NOTE]

Hemos presentado Notion MCP, un servidor MCP remoto con las siguientes mejoras:

• Instalación sencilla mediante OAuth estándar. Ya no necesitas manipular JSON ni tokens de API.
• Herramientas potentes adaptadas para agentes de IA, incluyendo la edición de páginas en Markdown. Estas herramientas están diseñadas pensando en un consumo optimizado de tokens.

Obtén más información y comienza en la documentación de Notion MCP.

Estamos priorizando, y solo brindamos soporte activo para, Notion MCP (remoto). Como resultado:

• Es posible que en el futuro retiremos este repositorio del servidor MCP local.
• Los issues y pull requests aquí no se monitorean activamente.
• Por favor, no registres issues relacionados con el MCP remoto aquí; en su lugar, contacta al soporte de Notion.

Este proyecto implementa un servidor MCP para la API de Notion.

---

⚠️ Cambios disruptivos de la versión 2.0.0

La versión 2.0.0 migra a la API de Notion 2025-09-03, la cual introduce las fuentes de datos como la abstracción principal para las bases de datos.

Qué cambió

Herramientas eliminadas (3):

• post-database-query - reemplazada por query-data-source
• update-a-database - reemplazada por update-a-data-source
• create-a-database - reemplazada por create-a-data-source

Nuevas herramientas (7):

• query-data-source - Consultar una fuente de datos (base de datos) con filtros y ordenamientos
• retrieve-a-data-source - Obtener metadatos y esquema de una fuente de datos
• update-a-data-source - Actualizar propiedades de una fuente de datos
• create-a-data-source - Crear una nueva fuente de datos
• list-data-source-templates - Listar plantillas disponibles en una fuente de datos
• move-page - Mover una página a una ubicación padre diferente
• retrieve-a-database - Obtener metadatos de la base de datos incluyendo sus IDs de fuente de datos

Cambios en parámetros:

• Todas las operaciones de base de datos ahora usan data_source_id en lugar de database_id
• Los valores de filtro de búsqueda cambiaron de ["page", "database"] a ["page", "data_source"]
• La creación de páginas ahora soporta padres tanto page_id como database_id (para fuentes de datos)

¿Necesito migrar?

No se requieren cambios de código. Las herramientas MCP se descubren automáticamente cuando el servidor se inicia. Cuando actualices a la v2.0.0, los clientes de IA verán automáticamente los nuevos nombres de herramientas y parámetros. Las antiguas herramientas de base de datos ya no están disponibles.

Si tienes nombres de herramientas codificados o prompts que hacen referencia a las herramientas de base de datos antiguas, actualízalos para usar las nuevas herramientas de fuente de datos:

Herramienta antigua (v1.x)	Nueva herramienta (v2.0)	Cambio de parámetro
post-database-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	Sin cambios (usa parent.page_id)

Nota: retrieve-a-database todavía está disponible y devuelve metadatos de la base de datos incluyendo la lista de IDs de fuente de datos. Usa retrieve-a-data-source para obtener el esquema y las propiedades de una fuente de datos específica.

Total de herramientas ahora: 22 (eran 19 en v1.x)

---

Contenido de página como Markdown

El servidor expone dos herramientas para trabajar con el contenido de la página como Markdown mejorado en lugar de JSON de bloques, lo cual es significativamente más eficiente en tokens para los agentes de IA:

• retrieve-page-markdown — Leer el contenido completo de una página como Markdown (GET /v1/pages/{page_id}/markdown). Pasa include_transcript: true para incluir las transcripciones de notas de reunión.
• update-page-markdown — Editar el contenido de una página con Markdown (PATCH /v1/pages/{page_id}/markdown). Prefiere replace_content para sobrescribir toda la página, o update_content para ediciones dirigidas de buscar y reemplazar.

Estos endpoints requieren la versión de API de Notion 2026-03-11. El servidor ahora obtiene el encabezado Notion-Version por operación desde la especificación OpenAPI, por lo que estas herramientas usan 2026-03-11 mientras que el resto de la API continúa usando 2025-09-03 — no se necesita configuración. Si tú mismo configuras Notion-Version a través de OPENAPI_MCP_HEADERS, tu valor tiene prioridad para cada herramienta.

---

Instalación

1. Configurar la integración en Notion

Ve a https://www.notion.so/profile/integrations y crea una nueva integración interna o selecciona una existente.

Si bien limitamos el alcance de la API de Notion expuesta (por ejemplo, no podrás eliminar bases de datos a través de MCP), existe un riesgo distinto de cero para los datos del espacio de trabajo al exponerlos a los LLM. Los usuarios preocupados por la seguridad pueden querer configurar aún más las Capacidades de la Integración.

Por ejemplo, puedes crear un token de integración de solo lectura otorgando solo acceso de "Leer contenido" desde la pestaña "Configuración":

2. Conectar contenido a la integración

Asegúrate de que las páginas y bases de datos relevantes estén conectadas a tu integración.

Para hacer esto, visita la pestaña Acceso en la configuración de tu integración interna. Edita el acceso y selecciona las páginas que te gustaría usar.

Alternativamente, puedes otorgar acceso a la página individualmente. Deberás visitar la página de destino, hacer clic en los 3 puntos y seleccionar "Conectar a la integración".

3. Agregar la configuración MCP a tu cliente

Usando npm

Cursor y Claude

Agrega lo siguiente a tu .cursor/mcp.json o claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Opción 1: Usando NOTION_TOKEN (recomendado)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Opción 2: Usando OPENAPI_MCP_HEADERS (para casos de uso avanzados)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

Agrega lo siguiente a tu settings.json

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

Usa la CLI de Copilot para agregar interactivamente el servidor MCP:

/mcp add

Alternativamente, crea o edita el archivo de configuración ~/.copilot/mcp-config.json y agrega:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Para más información, consulta la documentación de Copilot CLI.

Usando Docker

Hay dos opciones para ejecutar el servidor MCP con Docker:

Opción 1: Usando la imagen oficial de Docker Hub

Agrega lo siguiente a tu .cursor/mcp.json o claude_desktop_config.json

Usando NOTION_TOKEN (recomendado):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Usando OPENAPI_MCP_HEADERS (para casos de uso avanzados):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

Este enfoque:

• Utiliza la imagen oficial de Docker Hub
• Maneja correctamente el escape de JSON a través de variables de entorno
• Proporciona un método de configuración más confiable

Opción 2: Construir la imagen Docker localmente

También puedes construir y ejecutar la imagen Docker localmente. Primero, construye la imagen Docker:

docker compose build

Luego, agrega lo siguiente a tu .cursor/mcp.json o claude_desktop_config.json

Usando NOTION_TOKEN (recomendado):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

Usando OPENAPI_MCP_HEADERS (para casos de uso avanzados):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

No olvides reemplazar ntn_**** con tu secreto de integración. Encuéntralo en la pestaña de configuración de tu integración:

Opciones de transporte

El Servidor MCP de Notion soporta dos modos de transporte:

Transporte STDIO (predeterminado)

El modo de transporte predeterminado utiliza la entrada/salida estándar para la comunicación. Este es el transporte MCP estándar utilizado por la mayoría de los clientes como Claude Desktop.

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

Transporte HTTP transmitido en flujo continuo (Streamable HTTP)

Para aplicaciones basadas en web o clientes que prefieren la comunicación HTTP, puedes usar el transporte HTTP transmitido en flujo continuo:

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Al usar el transporte HTTP transmitido en flujo continuo, el servidor estará disponible en http://127.0.0.1:<port>/mcp de forma predeterminada.

Autenticación

El transporte HTTP transmitido en flujo continuo requiere autenticación de token de portador por seguridad. Tienes tres opciones:

Opción 1: Token autogenerado (solo para desarrollo)

npx @notionhq/notion-mcp-server --transport http

El servidor generará un token aleatorio seguro y lo escribirá en un archivo con permisos restringidos:

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

Opción 2: Token personalizado a través de la línea de comandos (recomendado para producción)

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Opción 3: Token personalizado a través de variable de entorno (recomendado para producción)

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

El argumento de línea de comandos --auth-token tiene prioridad sobre la variable de entorno AUTH_TOKEN si se proporcionan ambos.

Opción insegura: deshabilitar la autenticación HTTP

Puedes deshabilitar la autenticación de token de portador solo con la bandera insegura explícita:

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

ADVERTENCIA: --unsafe-disable-auth es inseguro. El servidor puede ser accesible para las páginas que visitas a través de DNS rebinding. Úsalo solo en una red aislada.

Cuando la autenticación está deshabilitada, el servidor habilita la protección contra DNS rebinding verificando los encabezados Host y Origin contra el host local configurado y los hosts de loopback. La bandera anterior --disable-auth todavía se acepta como un alias obsoleto, pero imprimirá una advertencia.

Realizar solicitudes HTTP

Todas las solicitudes al transporte HTTP transmitido en flujo continuo deben incluir el token de portador en el encabezado de Autorización:

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Nota: Asegúrate de configurar la variable de entorno NOTION_TOKEN (recomendado) o la variable de entorno OPENAPI_MCP_HEADERS con tu token de integración de Notion al usar cualquier modo de transporte.

Sirviendo múltiples integraciones (paso de token por solicitud)

Por defecto, el servidor se autentica en Notion con un único token incorporado al inicio, lo que bloquea un despliegue a una integración de Notion. Para permitir que un solo despliegue sirva múltiples integraciones, habilita el paso de token para que cada cliente proporcione su propio token de integración de Notion por conexión:

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

Luego, los clientes envían su token de Notion en la solicitud initialize usando el encabezado dedicado Notion-Token:

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Cómo se resuelve el token para cada conexión, en orden:

1. El encabezado Notion-Token (preferido — inequívoco, y funciona junto con la autenticación de puerta de enlace Authorization propia del servidor). Si está presente, debe ser un token de Notion válido, de lo contrario la solicitud se rechaza con 401.
2. Authorization: Bearer ntn_**** — solo cuando la autenticación de portador propia del servidor está desactivada (--unsafe-disable-auth), por lo que el encabezado está libre para llevar el token de Notion directamente.
3. De lo contrario, el token de entorno de inicio (NOTION_TOKEN / OPENAPI_MCP_HEADERS), si está configurado, para que el paso de token y una integración predeterminada puedan coexistir en un despliegue.

Notas:

• Solo los valores con un prefijo de token de Notion (ntn_, heredado secret_) se tratan como tokens de Notion, por lo que el secreto de puerta de enlace del servidor y el token de Notion de un inquilino nunca colisionan.
• Cada token está vinculado a su sesión MCP; los tokens nunca se registran (solo se emite un prefijo redactado).
• Esta es una configuración deliberada de paso de token. Despliégala siempre sobre TLS, y prefiere mantener habilitada la autenticación de portador propia del servidor (--auth-token) como una puerta de enlace frente al tráfico multiinquilino.

Ejemplos

1. Usando la siguiente instrucción

Comment "Hello MCP" on page "Getting started"

La IA planificará correctamente dos llamadas a la API, v1/search y v1/comments, para lograr la tarea

1. De manera similar, la siguiente instrucción resultará en una nueva página llamada "Notion MCP" agregada a la página padre "Development"

Add a page titled "Notion MCP" to page "Development"

1. También puedes hacer referencia al ID de contenido directamente

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Desarrollo

Construir y probar

npm run build
npm test

Ejecutar

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Probar cambios localmente en Cursor:

1. Ejecuta el comando npm link desde la raíz del repositorio para crear un enlace simbólico global de máquina al paquete notion-mcp-server.
2. Fusiona el fragmento de configuración a continuación en mcp.json de Cursor (u otro cliente MCP con el que quieras probar).
3. (Limpieza) ejecuta npm unlink desde la raíz del repositorio.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Publicar

npm login
npm publish --access public