Notion MCP Server

Notion MCP Server

Servidor MCP compatible con IA para la API de Notion. Ayuda a los agentes a encontrar, leer, consultar y actualizar espacios de trabajo de Notion, manteniendo respuestas lo suficientemente compactas para los flujos de trabajo diarios de IA.

Este servidor apunta a la API de Notion 2026-03-11 y utiliza el modelo actual de bases de datos/fuentes de datos. Expone herramientas MCP, prompts, recursos, resultados de herramientas estructurados y aplicaciones MCP opcionales para flujos de trabajo interactivos de Notion.

Características destacadas

• Búsqueda y descubrimiento de objetivos con notion_find.
• Lectura compacta de páginas con IDs de bloque estables mediante notion_read_page.
• Inspección de esquemas de fuentes de datos con notion_inspect_data_source.
• Consulta de fuentes de datos consciente del esquema y creación de elementos con valores simples.
• Herramientas simples de edición de páginas para párrafos, encabezados, listas, tareas pendientes, citas, destacados, bloques de código, divisores y anexado seguro de Markdown.
• Herramientas sin procesar de la API de Notion para operaciones avanzadas de bloques, páginas, bases de datos, fuentes de datos, comentarios y usuarios.
• Aplicaciones MCP opcionales: Explorador de fuentes de datos y Banco de trabajo de páginas.

Inicio rápido

Añade este servidor a un host MCP como Claude Desktop:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Reinicia tu host MCP después de guardar la configuración.

Guía de configuración

1. Crea una integración de Notion

Abre el panel de integraciones de Notion y crea una nueva integración interna.

2. Configura las capacidades

Concede solo las capacidades que necesites:

• Leer contenido: necesario para búsquedas, lecturas de páginas, recuperación de fuentes de datos y consultas.
• Insertar contenido: necesario para crear páginas/elementos y anexar bloques.
• Actualizar contenido: necesario para actualizar páginas, bloques y esquemas de fuentes de datos.
• Leer comentarios / Insertar comentarios: necesario solo para las herramientas de comentarios.
• Información de usuario: necesario solo al usar herramientas de búsqueda de usuarios.

Para una funcionalidad completa durante la configuración, habilita lectura, inserción y actualización de contenido. Añade capacidades de comentarios o usuarios solo si planeas usar esas herramientas.

3. Concede acceso al contenido

Abre la pestaña Acceso al contenido de tu integración y selecciona las páginas o bases de datos que quieras que el servidor MCP lea o edite.

También puedes conceder acceso desde la página o base de datos de Notion de destino: abre el menú ..., elige Conexiones y añade tu integración.

Notion solo permite que una integración acceda a páginas y bases de datos que se hayan compartido con ella. Una conexión añadida a una página también puede acceder a las páginas hijas de esa página.

4. Copia el token de integración interno

Copia el secreto de integración. Este valor se convierte en NOTION_API_TOKEN en la configuración de tu host MCP.

5. Configura tu host MCP

Para Cursor, Claude Desktop y otros hosts MCP, añade esta configuración de servidor a tus ajustes de MCP:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Para una copia local compilada:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Flujo de trabajo recomendado

1. Usa notion_find para localizar una página o fuente de datos.
2. Usa notion_read_page para el contexto de la página y los IDs de bloque editables.
3. Usa notion_inspect_data_source antes de consultar o crear elementos de fuentes de datos.
4. Usa notion_query_data_source_by_values y notion_create_data_source_item_from_values para el trabajo común con fuentes de datos.
5. Usa notion_append_markdown, notion_append_content, notion_update_content o notion_update_content_batch para ediciones normales de páginas.
6. Recurre a las herramientas JSON sin procesar solo cuando las herramientas simplificadas no cubran la forma de la API de Notion que necesitas.

Para desarrolladores

Estas referencias son principalmente para desarrollo, personalización y flujos de trabajo avanzados de MCP:

• Configuración: variables de entorno, argumentos de línea de comandos, ejemplos de hosts MCP, comandos de desarrollo y solución de problemas.
• Herramientas: referencia completa de herramientas agrupadas por área de flujo de trabajo.
• Flujos de trabajo: guía práctica de lectura, escritura, fuentes de datos, migración y manejo de errores.
• Aplicaciones MCP: detalles interactivos del Explorador de fuentes de datos y el Banco de trabajo de páginas.

Desarrollo

Este proyecto usa Node.js 22 o superior y pnpm.

pnpm install --frozen-lockfile
pnpm run build
pnpm test

Usa el inspector MCP durante el desarrollo local:

pnpm run inspector

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.