Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Servidor Notion MCP

[!NOTE]

Para la mejor experiencia, usa Remote Notion MCP, nuestro servidor MCP oficial alojado. Este repositorio es una implementación separada de un servidor MCP autoalojado que ya no se mantiene ni se soporta activamente. Por favor, usa Remote Notion MCP en su lugar. Está diseñado específicamente para dar a los agentes de IA resultados más rápidos usando muchos menos tokens.

Remote Notion MCP puede buscar en tu espacio de trabajo y aplicaciones conectadas de forma semántica, leer y editar páginas en Markdown, y devolver solo el contexto más relevante. Eso significa menos tiempo de espera, menos uso de la ventana de contexto y menores costos de tokens. También usa OAuth y respeta automáticamente los permisos existentes de Notion de cada usuario—sin tokens de API, configuración JSON, compartir páginas manualmente, ni un servidor local que mantener.

Característica	Remote Notion MCP	Este proyecto (local)
Experiencia rápida y alojada	✅	Se ejecuta y actualiza localmente
Respuestas eficientes en tokens	✅	Limitado
Herramientas potentes adaptadas para agentes de IA	✅	Herramientas básicas derivadas de la API
Búsqueda semántica en tu espacio de trabajo de Notion	✅	Solo búsqueda por palabras clave
Búsqueda de AI Connector en aplicaciones conectadas	✅	No disponible
Lectura y edición de páginas nativas en Markdown	✅	Limitado a dos herramientas de contenido de página
Configuración OAuth sin fricciones	✅	Configuración manual de token y JSON
Respeta los permisos existentes de Notion de cada usuario	✅	Permisos de integración manuales y compartir páginas
Soporte activo y mejoras continuas	✅	No soportado activamente

Aprende más y comienza en la documentación de Remote Notion MCP.

Estamos priorizando, y solo brindando soporte activo para, Remote Notion MCP. Como resultado:

• Es posible que este repositorio local del servidor MCP se retire en el futuro.
• Los problemas y solicitudes de extracción aquí no se monitorean activamente.
• Por favor, no reportes problemas 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 importantes en la versión 2.0.0

La versión 2.0.0 migra a la API de Notion 2025-09-03 que 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

Herramientas nuevas (7):

• query-data-source - Consulta una fuente de datos (base de datos) con filtros y ordenamientos
• retrieve-a-data-source - Obtén metadatos y esquema de una fuente de datos
• update-a-data-source - Actualiza las propiedades de la fuente de datos
• create-a-data-source - Crea una nueva fuente de datos
• list-data-source-templates - Lista las plantillas disponibles en una fuente de datos
• move-page - Mueve una página a una ubicación principal diferente
• retrieve-a-database - Obtén metadatos de la base de datos, incluidos sus IDs de fuente de datos

Cambios en los 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 admite tanto padres 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 se inicia el servidor. Cuando actualices a la v2.0.0, los clientes de IA verán automáticamente los nuevos nombres de herramientas y parámetros. Las herramientas de base de datos antiguas ya no están disponibles.

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

Herramienta antigua (v1.x)	Herramienta nueva (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 sigue disponible y devuelve metadatos de la base de datos, incluida 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 — Lee el contenido completo de una página como Markdown (GET /v1/pages/{page_id}/markdown). Pasa include_transcript: true para insertar transcripciones de notas de reuniones.
• update-page-markdown — Edita 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 específicas de buscar y reemplazar.

Estos endpoints requieren la versión 2026-03-11 de la API de Notion. 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 configuras Notion-Version tú mismo a través de OPENAPI_MCP_HEADERS, tu valor tiene prioridad para cada herramienta.

---

Instalación

1. Configuración de 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 lo expuesto de la API de Notion (por ejemplo, no podrás eliminar bases de datos a través de MCP), existe un riesgo no nulo para los datos del espacio de trabajo al exponerlos a los LLM. Los usuarios conscientes de 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 "Lectura de contenido" desde la pestaña "Configuración":

2. Conexión de 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 páginas individualmente. Deberás visitar la página de destino, hacer clic en los 3 puntos y seleccionar "Conectar a integración".

3. Agregar la configuración de 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:

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

Opción 2: Construyendo la imagen de Docker localmente

También puedes construir y ejecutar la imagen de Docker localmente. Primero, construye la imagen de 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 Notion MCP admite dos modos de transporte:

Transporte STDIO (predeterminado)

El modo de transporte predeterminado usa 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 transmisible

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

# 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"

Cuando se usa el transporte HTTP transmisible, el servidor estará disponible en http://127.0.0.1:<port>/mcp de forma predeterminada.

Autenticación

El transporte HTTP transmisible requiere autenticación de token de portador por seguridad. Tienes tres opciones:

Opción 1: Token generado automáticamente (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 el indicador explícito inseguro:

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

ADVERTENCIA: --unsafe-disable-auth es inseguro. El servidor puede ser accesible para páginas que visites mediante el reenlace de DNS. Úsalo solo en una red aislada.

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

Realizando solicitudes HTTP

Todas las solicitudes al transporte HTTP transmisible 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 (recomendada) o la variable de entorno OPENAPI_MCP_HEADERS con tu token de integración de Notion cuando uses cualquiera de los modos de transporte.

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

De forma predeterminada, el servidor se autentica en Notion con un solo token incorporado al inicio, lo que bloquea una implementación a una sola integración de Notion. Para permitir que una sola implementación sirva múltiples integraciones, habilita la transferencia 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

Los clientes luego 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 del propio 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 del propio servidor está desactivada (--unsafe-disable-auth), para que el encabezado quede 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 la transferencia y una integración predeterminada puedan coexistir en una sola implementación.

Notas:

• Solo los valores con un prefijo de token de Notion (ntn_, secret_ heredado) 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 chocan.
• 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 transferencia de token. Siempre impleméntala sobre TLS y prefiere mantener la autenticación de portador del propio servidor (--auth-token) habilitada 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 dará como resultado una nueva página llamada "Notion MCP" agregada a la página principal "Development"

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

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

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Desarrollo

Compilación y pruebas

npm run build
npm test

Ejecución

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 a nivel de máquina hacia el paquete notion-mcp-server.
2. Fusiona el fragmento de configuración a continuación en el archivo 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_..."
      }
    }
  }
}

Publicación

npm login
npm publish --access public