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

Notion MCP подключает ИИ-агента к рабочему пространству Notion без собственного сервера и ручного управления API-токенами. Агент получает инструменты для поиска, чтения и изменения доступного пользователю контента. Материал основан на официальной документации; реальный запуск подключения в рамках этой проверки не выполнялся.

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

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

Схема подключения выглядит так:

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

Notion также публикует пакет с открытым исходным кодом makenotion/notion-mcp-server, но активно его не поддерживает. Удалённый сервер получает актуальные инструменты и обновления; локальная версия остаётся вариантом для bearer-токенов, исходных JSON API v1 и самостоятельно управляемой инфраструктуры.

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

2 сентября 2026 года Notion разделил поиск на два инструмента:

• notion-search выполняет поиск по ключевым словам в Notion и ищет пользователей по имени или email. Для контента его используют, когда AI-поиск недоступен. Он поддерживает фильтры по расположению, создателю или редактору, дате, заголовку и статусу контента, сортировку и до 50 результатов; часть расширенных фильтров требует Business или Enterprise.
• notion-ai-search выполняет семантический поиск по Notion и доступным подключённым источникам, включая Slack, Mail, Calendar, Google Drive и Jira. Инструмент требует Notion AI.
• notion-fetch читает страницы, базы данных, источники данных и сохранённые представления по URL или ID. Вызов с id: self возвращает подключённого пользователя, рабочее пространство и карту доступности инструментов current_tool_access.

Перед поиском контента сначала вызовите notion-fetch с id: self. Если current_tool_access.ai_search.status показывает доступность AI-поиска, Notion рекомендует использовать notion-ai-search; иначе применяется notion-search.

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

Основные инструменты для работы с контентом:

• notion-create-pages создаёт страницы, применяет шаблоны баз данных, устанавливает обложки и значки; с creation_mode: "draft" страницу можно создать как приватный черновик без заранее выбранного родителя.
• notion-update-page изменяет свойства и содержимое страницы. Пакетные замены контента выполняются атомарно: если хотя бы одна изменяющая содержимое операция не находит нужную строку, сервер возвращает ошибку проверки, а страница остаётся без изменений. Для остальных операций old_str должен быть непустым и совпадать ровно в одном месте, если не задан replace_all_matches: true; операция с одинаковыми old_str и new_str игнорируется без проверки совпадения.
• notion-move-pages переносит страницы и базы данных.
• notion-duplicate-page запускает асинхронное копирование.
• notion-create-folder создаёт пустую папку под указанной страницей.
• notion-create-comment и notion-get-comments работают с комментариями и обсуждениями.

Для крупных операций создания и обновления можно запросить асинхронный режим через allow_async: true. Если сервер принимает запрос в асинхронную очередь, он возвращает идентификатор задачи; состояние проверяется через notion-get-async-task. Зависимые действия выполняйте только после статуса succeeded.

Для файлов доступны notion-create-file-upload, notion-create-attachment и notion-download-attachment для текстовых вложений. Прямая загрузка через MCP поддерживает файлы до 20 MiB; ограничения самого рабочего пространства продолжают действовать.

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

Notion MCP умеет:

• создавать базу данных, первый источник данных и первое представление через notion-create-database;
• изменять схему источника данных через notion-update-data-source;
• создавать и обновлять представления table, board, list, calendar, timeline, gallery, form, chart, map и dashboard;
• читать параметры сохранённого представления через notion-fetch с адресом view://...;
• получать строки, выполнять SQL-запросы и запускать сохранённые представления через notion-query-data-sources.

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

Доступность запросов зависит от тарифа:

• режим сохранённого представления (mode: "view") доступен на всех тарифах без отдельной квоты инструмента;
• SQL по одному или нескольким источникам данных не ограничен отдельной квотой на Business и Enterprise с Notion AI;
• на остальных тарифах SQL по одному источнику данных и режим rows используют измеряемый общий лимит рабочего пространства; после его исчерпания появляется предложение обновить тариф;
• режим rows сохраняет форматированный текст, упоминания и ссылки, которые SQL-вывод может опустить.

Точный набор возможностей для конкретного рабочего пространства лучше определять по current_tool_access, а не по заранее зашитой таблице тарифов.

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

Вариант для JSON-конфигурации

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

В минимальной конфигурации указан только URL: OAuth выполняется отдельно, поэтому токен в файл не добавляется.

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

Codex

Добавьте сервер в ~/.codex/config.toml или проектный .codex/config.toml:

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

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

codex mcp login notion

Авторизация и права

При первом подключении клиент откроет OAuth-страницу Notion. Выберите рабочее пространство и подтвердите доступ. Инструменты действуют с правами подключённого пользователя и могут читать или изменять доступный ему контент в рамках выданного подключения.

На 8 сентября 2026 года размещённый Notion MCP требует интерактивной OAuth-авторизации. Для полностью автоматических сценариев без участия пользователя может подойти self-hosted, то есть самостоятельно развёрнутый, пакет с bearer-токеном. Он требует собственной инфраструктуры, поддерживает исходные JSON API v1, но больше не поддерживается активно.

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

После OAuth попросите клиента выполнить безопасную операцию чтения:

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

Успешная проверка состоит из трёх наблюдаемых признаков:

1. fetch с id: self возвращает сведения о пользователе и рабочем пространстве.
2. Клиент выбирает ai-search или search с учётом current_tool_access.
3. fetch возвращает содержимое выбранной страницы без ошибки доступа.

Если авторизация не проходит, отключите и заново подключите сервер, затем проверьте права пользователя в нужном рабочем пространстве.

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

На дату проверки действуют следующие ограничения:

• средний персональный лимит — 180 запросов в минуту, или 3 запроса в секунду, суммарно по инструментам MCP;
• поиск по ключевым словам через notion-search, включая поиск пользователей, ограничен 30 запросами в минуту;
• notion-ai-search использует общий персональный лимит;
• отдельный лимит рабочего пространства делится между всеми подключениями и масштабируется по тарифу;
• после HTTP 429 клиент должен учитывать Retry-After и сокращать параллельные операции.

На Enterprise администраторы могут включить MCP Governance: разрешить конкретные MCP-клиенты и ИИ-приложения, заблокировать остальные и управлять подключениями на уровне рабочего пространства. Эти правила не отменяют обычную модель прав Notion.

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

Работа со спецификациями из IDE

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

Подготовка структурированной базы знаний

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

Сводка по проектам

Исходные данные: задачи распределены по одному или нескольким источникам данных. Агент вызывает notion-query-data-sources, применяет фильтры и группировку, затем формирует сводку. Результат можно сопоставить со строками, возвращёнными в режимах rows или view. SQL по нескольким источникам данных без отдельной квоты требует Business или Enterprise с Notion AI.

Официальные ссылки

• Обзор Notion MCP
• Подключение MCP-клиента
• Актуальный список инструментов и лимиты
• Админ-контроль Notion MCP
• Локальный сервер с открытым исходным кодом
• Журнал изменений Notion
• Репозиторий notion-mcp-server

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

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

Связанные материалы

• Статья: Как два ИИ-агента и один человек собрали этот сайт за ночь
• Блог: Страница, собранная в прямом эфире моего вебинара
• База знаний: Как не превратить Notion в свалку

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

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