Notion MCP — официальный сервер Notion для подключения ИИ-агентов

Notion MCP подключает ИИ-клиент к рабочему пространству Notion: агент ищет и читает доступный контент, создаёт страницы и базы данных, вносит правки и работает с подключёнными календарями. Размещённый сервер обслуживает Notion; собственный сервер для обычного подключения не нужен.

Что такое Notion MCP и как он устроен

Notion MCP — официальный сервер протокола Model Context Protocol, размещённый и поддерживаемый Notion. MCP задаёт способ, с помощью которого ИИ-клиент обнаруживает инструменты внешнего сервиса и вызывает их. На этом сервере доступны операции с Notion и, для пользовательских подключений, инструменты Calendar.

Обычное подключение устроено так:

1. Совместимый клиент — например, Codex, Claude Code, Cursor или VS Code — подключается к https://mcp.notion.com/mcp.
2. Пользователь проходит OAuth и выбирает рабочее пространство либо клиент передаёт разрешённый MCP-токен.
3. Сервер предоставляет инструменты, доступные этому подключению.
4. Агент вызывает их в пределах прав и ограничений подключения.

Notion MCP работает на всех тарифах, но отдельные функции требуют Business или Enterprise, иногда вместе с Notion AI. Подключаться могут участники рабочего пространства; гостям авторизация MCP недоступна.

Размещённый сервис обновляется на стороне Notion. Номер версии локального пакета не описывает его текущие возможности: при изменениях сверяйте документацию и список инструментов, который клиент получает через tools/list.

Notion также публикует локальный сервер с открытым исходным кодом — пакет makenotion/notion-mcp-server. Он больше не поддерживается активно. Это отдельная реализация с собственным развёртыванием, интеграционным токеном и исходными JSON API v1; её возможности нельзя приравнивать к актуальному размещённому серверу. Bearer-авторизация сама по себе больше не является причиной обязательно выбирать локальную версию: официальный удалённый сервер поддерживает MCP-токены.

Поиск и чтение контента

С 20 октября 2026 года в обычных сессиях размещённого сервера поиск разделён по источникам:

Для вопроса, охватывающего Notion и подключённые источники, вызывайте оба поисковых инструмента параллельно. Для конкретной страницы, которую нужно открыть или отредактировать, достаточно notion-search. Значимые результаты прочитайте перед использованием.

В notion-connector-search полный вопрос передаётся в question, характерные имена и термины — в keywords. Параметр lookback ограничивает период; sources позволяет выбрать источники. Ответ сообщает, какие источники проверены, и предупреждает о сбоях или пропущенных источниках. Ссылки на результаты открывают исходное приложение: notion-fetch не читает такие результаты.

Поиск по подключённым источникам требует Business или Enterprise с Notion AI и хотя бы одного настроенного источника. Если инструмент не появился, обновите список инструментов клиента или переподключите сервер. Для ChatGPT появление инструмента зависит также от проверки обновлённого приложения Notion на стороне OpenAI.

Фильтры, права и старые подключения

notion-search поддерживает фильтры по расположению, создателю, редактору, датам, заголовку и статусу контента, сортировку и до 50 результатов. Часть фильтров и сортировок требует полной версии Notion MCP на Business или Enterprise. На других тарифах неподдерживаемые условия могут быть отброшены: прочитайте notices, прежде чем считать результаты точно отфильтрованными. Поиск пользователей через query_type: "user" отдельно требует разрешений на сведения о пользователях; доступ к ИИ-поиску их не заменяет.

Старый notion-ai-search больше не публикуется в обычном tools/list, но остаётся вызываемым по имени для совместимости с клиентами, сохранившими прежний список. Он ищет по Notion и подключённым источникам вместе. Новые сценарии стройте на двух отдельных инструментах.

Исключение — подключения, принадлежащие рабочему пространству (workspace-owned). Они получают только выбранные администратором инструменты, не публикуют notion-connector-search и сохраняют прежнюю логику поиска. В таком подключении используйте фактически доступный notion-search или notion-ai-search и следуйте его описанию. При наличии ИИ-поиска notion-search здесь может искать и в Notion, и в подключённых источниках; точные фильтры и некоторые другие параметры переводят запрос на поиск внутри Notion.

Для обычного пользовательского подключения больше не требуется предварительно вызывать fetch self или проверять карту доступа перед каждым поиском: инструменты сами применяют ограничения. notion-get-tool-access нужен по ситуации; для workspace-owned сохраняются отдельные указания в описаниях инструментов. В карте current_tool_access новый поиск подключённых источников указан под ключом connector_search, а в workspace-owned — под ai_search при соответствующем выборе инструментов.

Создание и изменение страниц

Основные инструменты записи позволяют:

• notion-create-pages — создавать страницы, применять шаблоны, задавать обложки и значки. Режим creation_mode: "draft" создаёт приватную страницу и не сочетается с parent. Для верхнего уровня командного пространства доступен parent.teamspace_id, если подключение действует от пользователя с нужными правами; такой родитель тоже не сочетается с режимом приватного черновика.
• notion-update-page — менять свойства и текст, обложку и значок, применять шаблон. Для изменения только значка или обложки можно вызвать update_properties без properties.
• notion-move-pages — переносить страницы и базы; notion-duplicate-page — асинхронно копировать страницу.
• notion-create-folder и notion-update-folder — создавать папки, добавлять или убирать файлы, создавать вложенные папки.
• notion-delete-pages и notion-delete-databases — перемещать до 20 страниц или баз в корзину после явного подтверждения пользователя. Заблокированные объекты сначала нужно разблокировать. notion-restore-pages восстанавливает объекты; если родитель в корзине, сначала восстанавливают его. Верхнеуровневые страницы рабочего пространства пока восстанавливают через интерфейс Notion.

Частичная правка может завершиться с предупреждениями

С 16 октября 2026 года update_content применяет совпавшие поисково-заменяющие операции и пропускает несовпавшие. Они возвращаются в warnings с кодом no_match или indentation_mismatch. Ошибка всего запроса возникает, когда ни одна изменяющая содержимое операция не совпала. Поэтому прежнее правило «одна строка не найдена — вся пакетная правка отменяется» больше не действует.

Каждый old_str должен быть непустым и однозначно совпадать с текстом, если не указан replace_all_matches: true. Замена с одинаковыми old_str и new_str не считается изменением. Перед правкой прочитайте страницу; после — проверьте warnings и сохранённый текст. Полную замену используйте только когда намеренно заменяете всё содержимое, сохранив нужные вложенные объекты и ссылки.

Создание и обновление также могут успешно завершиться с предупреждением об автоматическом исправлении свойства. Например, ключ URL может быть сохранён как userDefined:URL. Используйте фактически возвращённые ключи и значения, а не исходное предположение.

Асинхронная запись

Для создания и обновления страниц доступен allow_async: true. Если вернулся async_task, проверяйте его через notion-get-async-task и передавайте возвращённый ID в task_id. Соблюдайте poll_after_seconds; зависимые действия выполняйте только после succeeded. В результате задачи тоже могут быть warnings.

Даже без явного асинхронного режима notion-update-page может вернуть задачу, если выполнение вышло за срок синхронного ожидания. Слишком крупный запрос разбивайте на меньшие операции: повтор идентичного запроса не исправляет ошибку размера.

Базы данных, источники данных и представления

База данных — контейнер с представлениями; источник данных хранит схему и строки. Перед запросом или записью прочитайте нужный источник через notion-fetch, получите его collection:// URL и точные имена свойств.

Notion MCP поддерживает:

• notion-create-database — создание базы, начального источника и первого представления;
• notion-update-data-source — изменение схемы и других параметров источника, а также макета страниц. Для изменения списка вариантов передавайте все варианты, которые нужно оставить; пропущенные варианты удаляются;
• notion-create-view и notion-update-view — представления table, board, list, calendar, timeline, gallery, form, chart, map и dashboard, их фильтры и отображение;
• notion-fetch с полученным view:// URL — чтение настроек сохранённого представления;
• notion-query-data-sources — SQL, чтение строк и выполнение сохранённого представления;
• notion-query-multiple-data-sources — один read-only SQLite-запрос к 2–100 источникам для объединений и сводок; требуется Business или Enterprise с Notion AI.

В каталоге и журнале изменений отражены новые детали схем: notion-fetch показывает default_option для Status. Не считайте первый вариант статусом по умолчанию: используйте указанное значение. При создании связанного представления notion-create-view принимает show_data_source_title, чтобы показать или скрыть заголовок источника над представлениями.

Выбор режима запроса

Инструмент notion-query-database-view удалён. Для сохранённого представления используйте notion-query-data-sources с mode: "view" и view_url внутри аргумента data.

SQL не наследует фильтры и сортировки представления: переносите условия в запрос явно либо выбирайте режим view. SQL-вывод может потерять форматирование, упоминания и адреса ссылок. Перед перезаписью такого свойства прочитайте его через rows или notion-fetch. Ответ с has_more не доказывает, что получены все строки; отсутствие курсора в rows нужно учитывать при полном обходе.

Указанное отсутствие отдельной квоты не отменяет общих ограничений частоты запросов. Конкретную доступность инструментов и параметров можно уточнить через notion-get-tool-access.

Файлы, обсуждения, Skills и календарь

Файлы и вложения

Для прямой загрузки есть notion-create-file-upload: в этом односоставном потоке поддерживаются файлы до 20 MiB, с учётом ограничений рабочего пространства. После успешной загрузки используйте возвращённый suggested_markdown. notion-create-attachment создаёт вложение из текста, прямого HTTPS-адреса или завершённой загрузки; notion-download-attachment читает поддерживаемые текстовые вложения до 200 KiB, созданные тем же подключением.

С 5 октября notion-fetch по умолчанию возвращает для файлов в блоках стабильные ссылки notion-file-block://, без подписанных адресов скачивания. При редактировании сохраняйте эти ссылки. Для скачивания используйте notion-get-file-download-urls — до 25 ссылок за вызов — или запросите include_file_urls: true. Это правило относится к файлам в блоках: файлы в свойствах базы по-прежнему могут содержать подписанные адреса. Истёкший адрес нужно получить заново.

Комментарии и связи страниц

notion-create-comment и notion-get-comments создают и читают комментарии и обсуждения. На Business и Enterprise доступны также редактирование и удаление собственных комментариев, реакции и закрытие или повторное открытие обсуждения через notion-update-comment, notion-delete-comment, notion-set-comment-reaction и notion-set-discussion-resolved. Закрывайте обсуждение только по прямому поручению человека.

notion-list-page-backlinks показывает доступные пользователю страницы того же рабочего пространства, которые ссылаются на материал или упоминают его. Это полезно перед переносом или удалением; инструмент не раскрывает недоступные страницы и не гарантирует полный аудит внешних ссылок. notion-get-groups позволяет узнать названия и ID видимых групп разрешений.

Повторяемые инструкции и память

Notion Skills — инструкции, сохранённые на страницах Notion. Размещённый MCP поддерживает получение включённых Skills, изменение их включения, загрузку и выгрузку пакетов через notion-get-enabled-skills, notion-update-enabled-skills, notion-download-skill и notion-upload-skill. Включение меняет настройки текущего пользователя; импорт пакета в существующий Skill заменяет его название, описание, текст и файлы. Это действие требует отдельного намерения, а не выполняется при обычном чтении.

Если у Skill нет вспомогательных файлов, скачивание возвращает markdown с полным SKILL.md; если файлы есть — временный URL архива. Для поиска ранее сохранённого контекста предусмотрен notion-memory-search. Эти инструменты не означают, что любой клиент автоматически использует все инструкции или всю память: ориентируйтесь на доступность и правила конкретного подключения. Форматы и ограничения описаны в каталоге инструментов MCP.

Подключённые календари

С 16 октября в пользовательских MCP-подключениях инструменты Calendar доступны на всех тарифах Notion. Они читают расписание и контакты, создают, меняют и отменяют события в подключённых календарях. Например: notion-calendar-list-calendars, notion-calendar-list-events, notion-calendar-create-events, notion-calendar-update-events, notion-calendar-cancel-events.

Сначала получите ссылку на календарь, затем — ID нужного события. Создание, изменение и отмена могут отправить уведомления участникам. Если пользователь не организатор, вместо отмены используйте доступное изменение ответа на приглашение. Для workspace-owned подключений инструменты Calendar недоступны. Поиск календарной информации через notion-connector-search — отдельная возможность со своими требованиями к Notion AI.

Подключение к MCP-клиенту

До настройки

Нужны аккаунт участника Notion, доступ к выбранному рабочему пространству и MCP-клиент с поддержкой Streamable HTTP и соответствующего способа авторизации. На корпоративном тарифе дополнительно проверьте, разрешён ли этот клиент администратором.

JSON-конфигурация

Для клиента, принимающего такой формат, минимальная конфигурация из официальной инструкции подключения:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Это пример структуры, а не универсальный файл для всех приложений. OAuth выполняется отдельно; токен в конфигурацию не добавляется. Streamable HTTP рекомендуется для новых подключений. SSE-адрес https://mcp.notion.com/sse оставлен для совместимости. Для клиента только со STDIO — стандартным вводом и выводом локального процесса — Notion описывает мост mcp-remote.

Codex

Добавьте сервер в ~/.codex/config.toml или проектный .codex/config.toml. По документации Codex проектная конфигурация загружается для доверенных проектов.

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

Затем запустите:

codex mcp login notion

Завершите OAuth в браузере и выберите нужное рабочее пространство. Хранение учётных данных оставьте клиенту; конфигурация проекта не должна содержать секреты.

Claude Code

Официальная инструкция Notion предлагает команду:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Затем выполните /mcp в Claude Code и пройдите OAuth. По умолчанию подключение локально для текущего проекта; --scope project делится настройкой через .mcp.json, а --scope user добавляет её для пользователя во всех проектах. Область конфигурации клиента не расширяет права в Notion.

OAuth, MCP-токены и корпоративная авторизация

Для личного подключения OAuth действует с правами подключённого пользователя. Агент может получить доступ к тому же контенту, который доступен этому пользователю; не считайте подключение ограниченным одной страницей без отдельной настройки прав.

На Business и Enterprise владелец рабочего пространства может создать токен через New MCP token в Developer portal и передавать его как bearer-токен на официальный MCP-адрес — без интерактивного входа через браузер. Это MCP-токен, а не обычный токен REST API. Держите его в защищённом хранилище секретов. Если подключаете такой токен в Codex, параметр bearer_token_env_var позволяет сослаться на переменную окружения вместо записи секрета в файл.

Workspace-owned подключения публикуют только выбранные администратором инструменты и имеют отличия от пользовательских сессий. Например, им недоступны новый отдельный поиск подключённых источников и Calendar. Проверяйте фактическую конфигурацию, а не переносите на них весь каталог возможностей.

На Enterprise с SAML SSO поддерживается также авторизация, управляемая корпоративным провайдером идентификации. Это отдельный способ подключения; не смешивайте его с персональным OAuth и MCP-токеном.

Как проверить подключение

После авторизации начните с безопасного чтения, без создания и удаления объектов.

Промпт:

Проверь подключение Notion MCP без изменений данных. Покажи имя рабочего пространства и пользователя через notion-get-self, если инструмент доступен. Найди в Notion страницу по слову «PRD», покажи ссылку и прочитай один подходящий результат. Если результатов нет, сообщи это и попроси ссылку на доступную мне тестовую страницу. Не используй подключённые источники и не меняй страницы.

Признаки успешной проверки:

1. notion-get-self возвращает ожидаемые workspace и user. Старый вызов notion-fetch с id: self сохраняется для совместимости, но для нового клиента рекомендуется отдельный инструмент идентификации. В bot-подключении ответ описывает бота, а не обязательно человека с email.
2. notion-search или указанный в описании workspace-owned подключения инструмент возвращает доступную тестовую страницу. Отсутствие результатов по случайному слову само по себе не доказывает поломку.
3. notion-fetch читает найденную страницу по её ID или URL без ошибки доступа.

Если нужно проверить запись, отдельно разрешите создание тестовой страницы в выбранном родителе. Затем прочитайте её обратно и сравните название, текст и свойства. При async_task сначала дождитесь succeeded; при warnings разберите каждое предупреждение. Удаляйте тестовую страницу только после отдельного подтверждения.

Что проверить при ошибке

Для диагностики тарифа и параметров используйте notion-get-tool-access; сам вызов не выдаёт новых прав.

Лимиты и админ-контроль

Частота запросов

На 24 октября 2026 года MCP использует стандартные ограничения запросов Notion. Для одного подключения действует бюджет на фиксированное 60-секундное окно:

Дополнительно действует общий лимит рабочего пространства, разделённый между всеми подключениями. Поэтому 429 возможен даже тогда, когда одно подключение не выбрало собственный бюджет.

6 октября Notion отменил отдельные MCP-лимиты для notion-search и notion-query-data-sources. Прежние «30 поисков в минуту» и введённые 28 сентября «20 поисков и 20 запросов к источникам за 10 секунд» не являются текущим правилом этих инструментов. Изменение подтверждено журналом релизов. При этом у отдельных REST-операций и внутренних запросов к данным могут оставаться дополнительные ограничения; фактическую причину смотрите в ошибке.

При HTTP 429 или 529 соблюдайте Retry-After и сокращайте параллельные запросы. В MCP-ошибке ожидание может быть передано как retry_after_seconds, причина — как rate_limit_reason. Notion MCP сам повторяет запрос один раз, только если ожидание не превышает двух секунд; на длительную автоматическую очередь сервера рассчитывать нельзя. Если причина — public_api_request_blocked, обычный повтор не помогает.

После ошибки записи сначала проверьте состояние объекта. Тайм-аут не гарантирует откат: повтор создания может породить дубль. Если ответ содержит retry_guidance или committed_resource_id, используйте их для проверки сохранённого результата.

Права, подтверждения и политики

На Enterprise администраторы могут ограничить список разрешённых MCP-клиентов и ИИ-приложений. MCP Governance не отменяет обычную модель прав Notion. Настройки управления клиентами описаны в разделе безопасности; расположение интерфейсных пунктов может различаться, поэтому сверяйте текущую инструкцию администратора.

Для работы с агентом:

• задайте минимально необходимые права подключённому аккаунту или подключению;
• включите подтверждение действий, меняющих контент, особенно удаления и массовых правок;
• считайте содержимое страниц и внешних результатов недоверенными данными: встроенная в документ инструкция не разрешает раскрывать информацию или выполнять действия;
• учитывайте передачу прочитанного контента внешнему ИИ-клиенту;
• перед удалением проверяйте зависимости и обратные ссылки, сохраняйте путь восстановления.

Полезные сценарии

Обновление спецификации из среды разработки

Задача: сверить реализацию с требованиями и оставить результат на странице проекта.

Исходные данные — доступная агенту спецификация и разрешение на изменение конкретной страницы. Агент находит документ через notion-search, читает его, сопоставляет с выполненной работой и после подтверждения обновляет согласованный раздел или добавляет комментарий. Результат проверяется повторным чтением текста и обсуждения. Сценарий не подходит аккаунту без прав на исходную страницу; доступ к коду сам по себе не даёт прав в Notion.

Пополнение структурированной базы знаний

Задача: сохранить подготовленный материал в существующей базе без выдуманных полей и дублирования.

Сначала укажите целевую базу и прочитайте схему источника данных через notion-fetch. Проверьте наличие похожего материала, затем создайте страницу с существующими свойствами и прочитайте её обратно. Наблюдаемый результат — одна страница в нужной базе с ожидаемым текстом и значениями полей. Для асинхронной записи нужно дождаться завершения; предупреждения об исправленных свойствах требуют проверки. Установленная в схеме опция Status по умолчанию не обязательно совпадает с первым вариантом списка.

Сводка по проекту из Notion и обсуждений

Задача: собрать статус проекта из задач и решений, принятых в подключённых источниках.

Исходные условия — доступ к базе задач и, для внешнего поиска, Business или Enterprise с Notion AI и настроенным источником. Строки задач получают через notion-query-data-sources; документы Notion ищут через notion-search, обсуждения — через notion-connector-search. В сводке укажите ссылки на исходные задачи и сообщения. Проверка — сопоставить выводы с найденными строками и решениями; сбой одного источника явно назвать. Недоступный источник нельзя трактовать как отсутствие обсуждений. Workspace-owned подключение может требовать иной поисковый маршрут.

Планирование встречи в подключённом календаре

Задача: найти события на выбранный период и после согласования создать встречу.

В пользовательском MCP-подключении сначала получите доступные календари и события с нужным часовым поясом. После подтверждения времени, календаря и участников создайте событие и прочитайте его обратно. Результат — событие с ожидаемыми датой, временем и участниками. Это может отправить приглашения; не выполняйте создание в рамках проверки только чтения. Для workspace-owned подключения этот сценарий недоступен.

Следующий шаг

Разобраться с базовым протоколом: MCP (Model Context Protocol) — стандарт подключения ИИ к внешним системам

Если вы проектируете доступ ИИ-агентов к рабочей базе знаний, полезно заранее определить роли, права и проверяемые границы автоматизации.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov