Servidor MCP de Notion

Servidor MCP para la API de Notion, que permite que LLM interactúe con los espacios de trabajo de Notion. Además, utiliza la conversión Markdown para reducir el tamaño del contexto al comunicarse con LLM, optimizando el uso de tokens y haciendo que las interacciones sean más eficientes.

Configuración

A continuación se ofrece una explicación detallada de los pasos mencionados anteriormente en los siguientes artículos:

• Versión en inglés: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
• Versión japonesa: https://qiita.com/suekou/items/44c864583f5e3e6325d9

1. Crear una integración de nociones :
   • Visita la página de Integraciones de Notion .
   • Haga clic en “Nueva integración”.
   • Nombre su integración y seleccione los permisos apropiados (por ejemplo, "Leer contenido", "Actualizar contenido").
2. Recuperar la clave secreta :
   • Copie el "Token de integración interna" de su integración.
   • Este token se utilizará para la autenticación.
3. Agregue la integración a su espacio de trabajo :
   • Abra la página o base de datos a la que desea que la integración acceda en Notion.
   • Haga clic en el botón "···" en la esquina superior derecha.
   • Haga clic en el botón "Conexiones" y seleccione la integración que creó en el paso 1 anterior.
4. Configurar Claude Desktop : agregue lo siguiente a su claude_desktop_config.json :

o

Variables de entorno

• NOTION_API_TOKEN (obligatorio): su token de integración de API de Notion.
• NOTION_MARKDOWN_CONVERSION : Establézcalo como "true" para habilitar la conversión experimental de Markdown. Esto puede reducir significativamente el consumo de tokens al visualizar contenido, pero puede causar problemas al intentar editar el contenido de la página.

Argumentos de la línea de comandos

• --enabledTools : Lista de herramientas separadas por comas para habilitar (p. ej., "notion_retrieve_page,notion_query_database"). Si se especifica, solo estarán disponibles las herramientas de la lista. Si no se especifica, se habilitarán todas las herramientas.

Ejemplo de herramientas de solo lectura (compatibles con copiar y pegar):

Configuración avanzada

Conversión de Markdown

De forma predeterminada, todas las respuestas se devuelven en formato JSON. Puede habilitar la conversión experimental a Markdown para reducir el consumo de tokens:

o

Cuando NOTION_MARKDOWN_CONVERSION se establece en "true" , las respuestas se convertirán al formato Markdown (si el parámetro format se establece en "markdown" ), lo que las hace más legibles y reduce significativamente el consumo de tokens. Sin embargo, dado que esta función es experimental, puede causar problemas al editar el contenido de la página, ya que la estructura original se pierde durante la conversión.

Puede controlar el formato según cada solicitud configurando el parámetro format en "json" o "markdown" en las llamadas a su herramienta:

• Utilice "markdown" para una mejor legibilidad cuando solo visualice contenido
• Utilice "json" cuando necesite modificar el contenido devuelto

Solución de problemas

Si encuentra errores de permisos:

1. Asegúrese de que la integración tenga los permisos necesarios.
2. Verifique que la integración esté invitada a las páginas o bases de datos relevantes.
3. Confirme que el token y la configuración estén configurados correctamente en claude_desktop_config.json .

Estructura del proyecto

El proyecto está organizado de forma modular para mejorar la mantenibilidad y la legibilidad:

Descripciones de directorios

• index.ts : Punto de entrada de la aplicación. Analiza los argumentos de la línea de comandos e inicia el servidor.
• cliente/ : Módulo responsable de la comunicación con la API de Notion.
  • index.ts : la clase NotionClientWrapper implementa todas las llamadas API.
• servidor/ : Implementación del servidor MCP.
  • index.ts : procesa las solicitudes recibidas de Claude y llama a los métodos de cliente apropiados.
• tipos/ : Módulo de definición de tipos.
  • index.ts : Exportaciones para todos los tipos.
  • args.ts : Definiciones de interfaz para argumentos de herramientas.
  • common.ts : Definiciones para esquemas comunes (formatos de ID, texto enriquecido, etc.).
  • responses.ts : Definiciones de tipos para las respuestas de la API de Notion.
  • schemas.ts : Definiciones para esquemas de herramientas MCP.
• utils/ : Funciones de utilidad.
  • index.ts : Funciona como herramientas habilitadas para filtrado.
• markdown/ : Funcionalidad de conversión de Markdown.
  • index.ts : Lógica para convertir respuestas JSON al formato Markdown.

Herramientas

Todas las herramientas admiten el siguiente parámetro opcional:

• format (cadena, "json" o "markdown", valor predeterminado: "markdown"): Controla el formato de la respuesta. Use "markdown" para una salida legible y "json" para acceder programáticamente a la estructura de datos original. Nota: La conversión a Markdown solo funciona cuando la variable de entorno NOTION_MARKDOWN_CONVERSION tiene el valor "true".

1. notion_append_block_children
   • Añadir bloques secundarios a un bloque principal.
   • Entradas requeridas:
     • block_id (cadena): El ID del bloque padre.
     • children (matriz): Matriz de objetos de bloque para agregar.
   • Devuelve: Información sobre los bloques añadidos.
2. notion_retrieve_block
   • Recuperar información sobre un bloque específico.
   • Entradas requeridas:
     • block_id (cadena): El ID del bloque a recuperar.
   • Devuelve: Información detallada sobre el bloque.
3. notion_retrieve_block_children
   • Recuperar los hijos de un bloque específico.
   • Entradas requeridas:
     • block_id (cadena): El ID del bloque padre.
   • Entradas opcionales:
     • start_cursor (cadena): Cursor para la siguiente página de resultados.
     • page_size (número, predeterminado: 100, máximo: 100): Número de bloques a recuperar.
   • Devuelve: Lista de bloques secundarios.
4. notion_delete_block
   • Eliminar un bloque específico.
   • Entradas requeridas:
     • block_id (cadena): El ID del bloque a eliminar.
   • Devuelve: Confirmación de la eliminación.
5. notion_retrieve_page
   • Recuperar información sobre una página específica.
   • Entradas requeridas:
     • page_id (cadena): El ID de la página a recuperar.
   • Devuelve: Información detallada sobre la página.
6. notion_update_page_properties
   • Actualizar las propiedades de una página.
   • Entradas requeridas:
     • page_id (cadena): El ID de la página a actualizar.
     • properties (objeto): Propiedades a actualizar.
   • Devuelve: Información sobre la página actualizada.
7. notion_create_database
   • Crear una nueva base de datos.
   • Entradas requeridas:
     • parent (objeto): Objeto padre de la base de datos.
     • properties (objeto): Esquema de propiedades de la base de datos.
   • Entradas opcionales:
     • title (matriz): título de la base de datos como una matriz de texto enriquecido.
   • Devuelve: Información sobre la base de datos creada.
8. notion_query_database
   • Consultar una base de datos.
   • Entradas requeridas:
     • database_id (cadena): El ID de la base de datos a consultar.
   • Entradas opcionales:
     • filter (objeto): Condiciones de filtro.
     • sorts (matriz): Condiciones de ordenación.
     • start_cursor (cadena): Cursor para la siguiente página de resultados.
     • page_size (número, predeterminado: 100, máximo: 100): Número de resultados a recuperar.
   • Devuelve: Lista de resultados de la consulta.
9. notion_retrieve_database
   • Recuperar información sobre una base de datos específica.
   • Entradas requeridas:
     • database_id (cadena): El ID de la base de datos a recuperar.
   • Devuelve: Información detallada sobre la base de datos.
10. notion_update_database

• Actualizar información sobre una base de datos.
• Entradas requeridas:
  • database_id (cadena): El ID de la base de datos a actualizar.
• Entradas opcionales:
  • title (matriz): nuevo título para la base de datos.
  • description (matriz): Nueva descripción para la base de datos.
  • properties (objeto): esquema de propiedades actualizado.
• Devuelve: Información sobre la base de datos actualizada.

11. notion_create_database_item

• Crear un nuevo elemento en una base de datos de Notion.
• Entradas requeridas:
  • database_id (cadena): El ID de la base de datos a la que se agregará el elemento.
  • properties (objeto): Las propiedades del nuevo elemento. Deben coincidir con el esquema de la base de datos.
• Devoluciones: Información sobre el artículo recién creado.

12. notion_search

• Buscar páginas o bases de datos por título.
• Entradas opcionales:
  • query (cadena): Texto a buscar en los títulos de páginas o bases de datos.
  • filter (objeto): Criterios para limitar los resultados sólo a páginas o sólo a bases de datos.
  • sort (objeto): Criterios para ordenar los resultados
  • start_cursor (cadena): cursor de inicio de paginación.
  • page_size (número, predeterminado: 100, máximo: 100): Número de resultados a recuperar.
• Devuelve: Lista de páginas o bases de datos coincidentes.

13. notion_list_all_users

• Enumere todos los usuarios en el espacio de trabajo de Notion.
• Nota: Esta función requiere actualizar al plan Notion Enterprise y utilizar una clave API de organización para evitar errores de permisos.
• Entradas opcionales:
  • start_cursor (cadena): cursor de inicio de paginación para enumerar usuarios.
  • page_size (número, máximo: 100): Número de usuarios a recuperar.
• Devuelve: una lista paginada de todos los usuarios en el espacio de trabajo.

14. notion_retrieve_user

• Recuperar un usuario específico por user_id en Notion.
• Nota: Esta función requiere actualizar al plan Notion Enterprise y utilizar una clave API de organización para evitar errores de permisos.
• Entradas requeridas:
  • user_id (cadena): El ID del usuario a recuperar.
• Devuelve: Información detallada sobre el usuario especificado.

15. notion_retrieve_bot_user

• Recupera el usuario bot asociado con el token actual en Notion.
• Devuelve: Información sobre el usuario del bot, incluidos los detalles de la persona que autorizó la integración.

16. notion_create_comment

• Crear un comentario en Notion.
• Requiere que la integración tenga capacidades de 'insertar comentario'.
• Especifique un objeto parent con un page_id o un discussion_id , pero no ambos.
• Entradas requeridas:
  • rich_text (matriz): matriz de objetos de texto enriquecido que representan el contenido del comentario.
• Entradas opcionales:
  • parent (objeto): debe incluir page_id si se utiliza.
  • discussion_id (cadena): un ID de hilo de discusión existente.
• Devuelve: Información sobre el comentario creado.

17. notion_retrieve_comments

• Recupera una lista de comentarios no resueltos de una página o un bloque de Notion.
• Requiere que la integración tenga capacidades de "leer comentarios".
• Entradas requeridas:
  • block_id (cadena): el ID del bloque o página cuyos comentarios desea recuperar.
• Entradas opcionales:
  • start_cursor (cadena): cursor de inicio de paginación.
  • page_size (número, máximo: 100): Número de comentarios a recuperar.
• Devuelve: una lista paginada de comentarios asociados con el bloque o página especificados.

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.