Notion MCP Server

Сервер Notion MCP

MCP Server для Notion API, позволяющий LLM взаимодействовать с рабочими пространствами Notion. Кроме того, он использует преобразование Markdown для уменьшения размера контекста при общении с LLM, оптимизируя использование токенов и делая взаимодействие более эффективным.

Настраивать

Ниже приведено подробное объяснение шагов, упомянутых выше в следующих статьях:

• Английская версия: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
• Японская версия: https://qiita.com/suekou/items/44c864583f5e3e6325d9

1. Создать понятие интеграции :
   • Посетите страницу Notion Your Integrations .
   • Нажмите «Новая интеграция».
   • Дайте название вашей интеграции и выберите соответствующие разрешения (например, «Чтение содержимого», «Обновление содержимого»).
2. Получить секретный ключ :
   • Скопируйте «Внутренний токен интеграции» из вашей интеграции.
   • Этот токен будет использоваться для аутентификации.
3. Добавьте интеграцию в свое рабочее пространство :
   • Откройте страницу или базу данных, к которой вы хотите получить доступ для интеграции в Notion.
   • Нажмите кнопку «···» в правом верхнем углу.
   • Нажмите кнопку «Подключения» и выберите интеграцию, созданную на шаге 1 выше.
4. Настройте Claude Desktop : добавьте следующее в ваш claude_desktop_config.json :

или

Переменные среды

• NOTION_API_TOKEN (обязательно): ваш токен интеграции API Notion.
• NOTION_MARKDOWN_CONVERSION : Установите значение "true", чтобы включить экспериментальное преобразование Markdown. Это может значительно сократить потребление токенов при просмотре контента, но может вызвать проблемы при попытке редактирования контента страницы.

Аргументы командной строки

• --enabledTools : разделенный запятыми список инструментов для включения (например, "notion_retrieve_page,notion_query_database"). Если указано, будут доступны только перечисленные инструменты. Если не указано, включены все инструменты.

Пример инструментов только для чтения (удобен для копирования и вставки):

Расширенная конфигурация

Преобразование уценки

По умолчанию все ответы возвращаются в формате JSON. Вы можете включить экспериментальную конвертацию Markdown, чтобы сократить потребление токенов:

или

Если параметру NOTION_MARKDOWN_CONVERSION присвоено значение "true" , ответы будут преобразованы в формат Markdown (если параметр format установлен на "markdown" ), что сделает их более удобными для восприятия человеком и значительно сократит потребление токенов. Однако, поскольку эта функция является экспериментальной, она может вызвать проблемы при попытке редактирования содержимого страницы, поскольку исходная структура будет потеряна при преобразовании.

Вы можете управлять форматом для каждого запроса, устанавливая параметр format на "json" или "markdown" в вызовах инструментов:

• Используйте "markdown" для лучшей читабельности только при просмотре контента.
• Используйте "json" когда вам нужно изменить возвращаемое содержимое.

Поиск неисправностей

Если вы столкнулись с ошибками разрешений:

1. Убедитесь, что интеграция имеет необходимые разрешения.
2. Убедитесь, что интеграция приглашена на соответствующие страницы или в базы данных.
3. Убедитесь, что токен и конфигурация правильно установлены в claude_desktop_config.json .

Структура проекта

Проект организован по модульному принципу для улучшения удобства обслуживания и читаемости:

Описания каталогов

• index.ts : Точка входа приложения. Анализирует аргументы командной строки и запускает сервер.
• client/ : Модуль, отвечающий за взаимодействие с Notion API.
  • index.ts : Класс NotionClientWrapper реализует все вызовы API.
• server/ : Реализация сервера MCP.
  • index.ts : обрабатывает запросы, полученные от Клода, и вызывает соответствующие клиентские методы.
• types/ : Модуль определения типа.
  • index.ts : Экспорт для всех типов.
  • args.ts : Определения интерфейсов для аргументов инструментов.
  • common.ts : Определения для общих схем (форматы идентификаторов, расширенный текст и т. д.).
  • responses.ts : Определения типов для ответов Notion API.
  • schemas.ts : Определения схем инструментов MCP.
• utils/ : Вспомогательные функции.
  • index.ts : Функции, подобные инструментам с поддержкой фильтрации.
• markdown/ : Функциональность преобразования Markdown.
  • index.ts : Логика для преобразования ответов JSON в формат Markdown.

Инструменты

Все инструменты поддерживают следующий необязательный параметр:

• format (string, "json" или "markdown", по умолчанию: "markdown"): управляет форматом ответа. Используйте "markdown" для вывода, удобного для восприятия человеком, "json" для программного доступа к исходной структуре данных. Примечание: преобразование Markdown работает только в том случае, если переменная среды NOTION_MARKDOWN_CONVERSION имеет значение "true".

1. notion_append_block_children
   • Добавлять дочерние блоки к родительскому блоку.
   • Требуемые входные данные:
     • block_id (строка): идентификатор родительского блока.
     • children (массив): Массив блочных объектов для добавления.
   • Возвращает: информацию о добавленных блоках.
2. notion_retrieve_block
   • Получить информацию о конкретном блоке.
   • Требуемые входные данные:
     • block_id (строка): идентификатор блока, который необходимо получить.
   • Возвращает: Подробную информацию о блоке.
3. notion_retrieve_block_children
   • Извлечь дочерние элементы определенного блока.
   • Требуемые входные данные:
     • block_id (строка): идентификатор родительского блока.
   • Дополнительные входные данные:
     • start_cursor (string): Курсор для следующей страницы результатов.
     • page_size (число, по умолчанию: 100, макс.: 100): Количество блоков для извлечения.
   • Возвращает: список дочерних блоков.
4. notion_delete_block
   • Удалить определенный блок.
   • Требуемые входные данные:
     • block_id (строка): идентификатор блока, который нужно удалить.
   • Возврат: Подтверждение удаления.
5. notion_retrieve_page
   • Получить информацию о конкретной странице.
   • Требуемые входные данные:
     • page_id (строка): идентификатор страницы, которую необходимо получить.
   • Возвращает: Подробную информацию о странице.
6. notion_update_page_properties
   • Обновить свойства страницы.
   • Требуемые входные данные:
     • page_id (строка): идентификатор страницы для обновления.
     • properties (объект): Свойства для обновления.
   • Возвращает: информацию об обновленной странице.
7. notion_create_database
   • Создайте новую базу данных.
   • Требуемые входные данные:
     • parent (объект): Родительский объект базы данных.
     • properties (объект): Схема свойств базы данных.
   • Дополнительные входные данные:
     • title (array): Заголовок базы данных в виде расширенного текстового массива.
   • Возвращает: информацию о созданной базе данных.
8. notion_query_database
   • Запрос к базе данных.
   • Требуемые входные данные:
     • database_id (строка): идентификатор базы данных для запроса.
   • Дополнительные входные данные:
     • filter (объект): Условия фильтра.
     • sorts (массив): Условия сортировки.
     • start_cursor (string): Курсор для следующей страницы результатов.
     • page_size (число, по умолчанию: 100, макс.: 100): Количество результатов для извлечения.
   • Возвращает: Список результатов запроса.
9. notion_retrieve_database
   • Извлечение информации о конкретной базе данных.
   • Требуемые входные данные:
     • database_id (строка): идентификатор базы данных, которую необходимо получить.
   • Возвращает: Подробную информацию о базе данных.
10. notion_update_database

• Обновление информации о базе данных.
• Требуемые входные данные:
  • database_id (строка): идентификатор базы данных для обновления.
• Дополнительные входные данные:
  • title (массив): Новое название базы данных.
  • description (массив): Новое описание для базы данных.
  • properties (объект): Обновленная схема свойств.
• Возвращает: информацию об обновленной базе данных.

11. notion_create_database_item

• Создайте новый элемент в базе данных Notion.
• Требуемые входные данные:
  • database_id (строка): идентификатор базы данных, в которую необходимо добавить элемент.
  • properties (объект): Свойства нового элемента. Они должны соответствовать схеме базы данных.
• Возврат: Информация о вновь созданном элементе.

12. notion_search

• Поиск страниц или баз данных по названию.
• Дополнительные входные данные:
  • query (строка): Текст для поиска в заголовках страниц или баз данных.
  • filter (объект): Критерии ограничения результатов только страницами или только базами данных.
  • sort (объект): Критерии сортировки результатов
  • start_cursor (строка): Курсор начала пагинации.
  • page_size (число, по умолчанию: 100, макс.: 100): Количество результатов для извлечения.
• Возвращает: список соответствующих страниц или баз данных.

13. notion_list_all_users

• Перечислите всех пользователей в рабочей области Notion.
• Примечание: для этой функции требуется обновление до плана Notion Enterprise и использование ключа API организации, чтобы избежать ошибок разрешений.
• Дополнительные входные данные:
  • start_cursor (string): Начальный курсор пагинации для списка пользователей.
  • page_size (число, макс.: 100): Количество пользователей для извлечения.
• Возвращает: постраничный список всех пользователей в рабочей области.

14. notion_retrieve_user

• Получить определенного пользователя по user_id в Notion.
• Примечание: для этой функции требуется обновление до плана Notion Enterprise и использование ключа API организации, чтобы избежать ошибок разрешений.
• Требуемые входные данные:
  • user_id (строка): идентификатор пользователя, которого необходимо получить.
• Возвращает: Подробную информацию об указанном пользователе.

15. notion_retrieve_bot_user

• Получить пользователя бота, связанного с текущим токеном в Notion.
• Возвращает: информацию о пользователе бота, включая данные лица, авторизовавшего интеграцию.

16. notion_create_comment

• Создайте комментарий в Notion.
• Требует интеграции с возможностью «вставки комментариев».
• Укажите parent объект либо с помощью page_id , либо с помощью discussion_id , но не оба одновременно.
• Требуемые входные данные:
  • rich_text (array): Массив объектов форматированного текста, представляющих содержимое комментария.
• Дополнительные входные данные:
  • parent (объект): должен включать page_id если используется.
  • discussion_id (строка): идентификатор существующей темы обсуждения.
• Возвращает: информацию о созданном комментарии.

17. notion_retrieve_comments

• Получить список неразрешенных комментариев со страницы или блока Notion.
• Требует интеграции с возможностью «чтения комментариев».
• Требуемые входные данные:
  • block_id (строка): идентификатор блока или страницы, комментарии к которой вы хотите получить.
• Дополнительные входные данные:
  • start_cursor (строка): Курсор начала пагинации.
  • page_size (число, макс.: 100): Количество комментариев для извлечения.
• Возвращает: постраничный список комментариев, связанных с указанным блоком или страницей.

Лицензия

Этот сервер MCP лицензирован по лицензии MIT. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение в соответствии с условиями лицензии MIT. Для получения более подробной информации см. файл LICENSE в репозитории проекта.