notion-mcp-server

Servidor MCP de Notion

El Servidor MCP de Notion es una implementación de servidor del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con la API de Notion. Este servidor, listo para producción, proporciona un conjunto completo de herramientas y puntos finales para leer, crear y modificar contenido de Notion mediante interacciones de lenguaje natural.

🚧 Desarrollo Activo : ¡Ya está disponible la compatibilidad con bases de datos! Se han añadido herramientas para comentarios y gestión de usuarios. Si este proyecto te resulta útil, considera darle una estrella; me ayuda a saber que este trabajo es valioso para la comunidad y motiva a seguir desarrollando.

📑 Índice de contenidos

• Primeros pasos e integración
  • Proceso de configuración
  • Integración del cursor
  • Integración de escritorio de Claude
• Características
• Documentación
  • Herramientas disponibles
  • Recursos disponibles
• Desarrollo
• Detalles técnicos
• Solución de problemas
• Contribuyendo
• Licencia

🚀 Primeros pasos e integración

Proceso de configuración

1. Obtener una clave API de Notion
   • Crear una integración en Notion Developers
   • Copia tu clave API
2. Habilitar la integración para sus páginas
   • Seleccione una página existente o cree una nueva en Notion
   • Haga clic en el menú "..." en la esquina superior derecha
   • Vaya a "Conexiones"
   • Encuentre y habilite su integración desde la lista
3. Elija su método de integración
   • Siga una de las opciones de integración a continuación según su cliente MCP preferido
4. Pídale a su asistente de IA que interactúe con Notion
   • "Crear una nueva página con las tareas de hoy"
   • Actualizar mis notas de reunión en Notion
   • "Añadir viñetas a la página de notas de mi reunión"
   • "Crear una nueva base de datos para el seguimiento de proyectos"
   • "Añadir nuevas entradas a mi base de datos de tareas"
   • "Añadir un comentario a mi página de proyecto"
   • "Muéstrame todos los comentarios de este documento"
   • "Enumerar todos los usuarios en mi espacio de trabajo"
   • "Obtener información sobre un usuario específico"

Integración del cursor

Método 1: Usar mcp.json

1. Cree o edite el archivo .cursor/mcp.json en el directorio de su proyecto:

2. Reemplace YOUR_KEY y YOUR_PAGE_ID con su clave de API de Notion y el ID de página reales
3. Reinicie el cursor para aplicar los cambios

Método 2: Modo manual

1. Abra Cursor y vaya a Configuración
2. Vaya a la sección "MCP" o "Protocolo de contexto de modelo"
3. Haga clic en "Agregar servidor" o equivalente
4. Introduzca el siguiente comando en el campo correspondiente:

5. Reemplace YOUR_KEY y YOUR_PAGE_ID con su clave de API de Notion y el ID de página reales
6. Guarde la configuración y reinicie Cursor si es necesario

Integración de escritorio de Claude

1. Cree o edite el archivo mcp.json en su directorio de configuración:

2. Reemplace YOUR_KEY y YOUR_PAGE_ID con su clave de API de Notion y el ID de página reales
3. Reinicie Claude Desktop para aplicar los cambios

🌟 Características

• 📝 Integración con Notion : interactúa con bases de datos, páginas y bloques de Notion
• 🔌 Compatibilidad universal con MCP : funciona con todos los clientes MCP, incluidos Cursor, Claude Desktop, Cline y Zed
• 🔍 Recuperación de datos : obtenga información de páginas, bloques y bases de datos de Notion
• ✏️ Creación de contenido : crea y actualiza páginas y bloques de Notion
• 📊 Gestión de bloques : agregue, actualice y elimine bloques dentro de las páginas de Notion
• 💾 Operaciones de base de datos : crear, consultar y actualizar bases de datos
• Operaciones por lotes : realice múltiples operaciones en una sola solicitud
• 🗑️ Archivar y restaurar : archivar y restaurar páginas de Notion
• 🔎 Funcionalidad de búsqueda : busca páginas y bases de datos de Notion por título
• 💬 Gestión de comentarios : obtenga, cree y responda comentarios en páginas y debates
• 👥 Gestión de usuarios : recupera usuarios del espacio de trabajo e información de usuarios

📚 Documentación

Herramientas disponibles

El servidor proporciona las siguientes herramientas consolidadas para interactuar con Notion:

notion_pages

Una herramienta integral para operaciones de página que incluye:

• Crear nuevas páginas con contenido específico
• Actualización de las propiedades de la página
• Archivar páginas (mover a la papelera)
• Restaurar páginas previamente archivadas
• Búsqueda de páginas por título

Operaciones de ejemplo:

notion_blocks

Un kit de herramientas completo para operaciones de bloques que incluye:

• Recuperando el contenido del bloque
• Obteniendo bloques secundarios
• Agregar nuevos bloques a un padre
• Actualización de bloques existentes
• Eliminando bloques
• Realizar operaciones por lotes (añadir, actualizar, eliminar, mixtas)

Operaciones de ejemplo:

notion_database

Una poderosa herramienta para interacciones con bases de datos que incluye:

• Creación de nuevas bases de datos con propiedades personalizadas
• Consulta de bases de datos con filtros y ordenamiento
• Actualización de la estructura y las propiedades de la base de datos

Operaciones de ejemplo:

notion_comments

Una herramienta para gestionar comentarios sobre el contenido de Notion:

• Recuperar comentarios de páginas y bloques
• Agregar nuevos comentarios a las páginas
• Respondiendo a las discusiones existentes

Operaciones de ejemplo:

notion_users

Una herramienta para acceder a la información del usuario:

• Listado de todos los usuarios del espacio de trabajo
• Obtener detalles sobre usuarios específicos
• Recuperando información sobre el usuario actual del bot

Operaciones de ejemplo:

Recursos disponibles

Actualmente, el servidor no expone ningún recurso y se centra en operaciones basadas en herramientas.

🛠 Desarrollo

1. Clonar el repositorio
   git clone https://github.com/awkoy/notion-mcp-server.git cd notion-mcp-server
2. Instalar dependencias
   npm install
3. Configurar variables de entorno
   • Crea un archivo .env con:
     NOTION_TOKEN=your_notion_api_key NOTION_PAGE_ID=your_notion_page_id
4. Construir el proyecto
   npm run build
5. Ejecutar el Inspector
   npm run inspector

🔧 Detalles técnicos

• Desarrollado con TypeScript y el SDK de MCP (versión 1.7.0+)
• Utiliza el cliente API oficial de Notion (@notionhq/client v2.3.0+)
• Sigue la especificación del Protocolo de Contexto de Modelo
• Implementa herramientas para operaciones CRUD en páginas, bloques y bases de datos de Notion
• Admite operaciones por lotes eficientes para optimizar el rendimiento
• Valida la entrada/salida con esquemas Zod

❓ Solución de problemas

• Problemas comunes
  • Errores de autenticación : asegúrese de que su token de Notion tenga los permisos correctos y que la integración esté habilitada para sus páginas/bases de datos
  • Problemas de acceso a la página : asegúrese de que su integración se haya agregado a las páginas a las que intenta acceder
  • Limitación de velocidad : Notion API tiene límites de velocidad: utilice operaciones por lotes para optimizar las solicitudes
• Obtener ayuda
  • Crear un problema en el repositorio de GitHub
  • Consulte la documentación de la API de Notion
  • Visita los canales de la comunidad MCP para obtener ayuda

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

1. Bifurcar el repositorio
2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )
4. Empujar a la rama ( git push origin feature/amazing-feature )
5. Abrir una solicitud de extracción

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.