Notion MCP (awkoy)
Notion MCP Server (awkoy)
Notion MCP на токене: агент ищет страницы, ведет базы, правит блоки и комментарии через три инструмента и 47 операций, без ручного входа
- 179 ★ репозитория
- Последний коммит
- MIT
Широкий доступ
Почему такой уровень
- Агент создает, правит и архивирует страницы, базы и комментарии от вашего имени
- Личный токен открывает все страницы, которые видите вы, а не отдельные выбранные
Установка
- Работает в
Ручная установка
npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_hereУтилита add-mcp находит установленных агентов и записывает настройки для выбранных. Флаг `--env` не убирайте: без него токена в записи не будет.
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Агент создает, правит и архивирует страницы, базы и комментарии от вашего имени
- Личный токен открывает все страницы, которые видите вы, а не отдельные выбранные
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Notion MCP от автора awkoy подключает агента к рабочему пространству Notion по токену, без подтверждения входа в браузере. Сервер ставится как npm-пакет `notion-mcp-server` и запускается через `npx` по stdio. В переменной `NOTION_TOKEN` лежит либо личный токен (`ntn_…`), тогда агент видит все, что видите вы, либо секрет внутренней интеграции, тогда только страницы, к которым вы ее подключили. Вместо инструмента на каждый метод API сервер открывает три: `notion_read` для чтения, `notion_write` для записи и `notion_describe`, который по запросу отдает схему одной операции с рабочим примером. За ними стоят 47 операций: поиск и правка страниц, блоки, базы, источники данных, представления баз, шаблоны, комментарии, пользователи и загрузка файлов. Страницу можно прочитать и переписать целиком в Markdown, а свойства строки базы записываются обычными значениями вроде `Status: "Done"`: типы сервер берет из схемы источника данных. Каждая записывающая операция принимает список элементов. До 10 из них выполняются параллельно, режим `atomic` останавливает пакет на первой ошибке и пытается архивировать уже созданное, а `idempotency_key` в течение 5 минут возвращает прежний результат вместо повторной записи. Запросы к Notion идут через ограничитель частоты, по умолчанию 3 в секунду, с повтором при превышении лимита.
Для кого. Для разработчиков и команд, которые ведут задачи, заметки и базы знаний в Notion и поручают агенту в Claude Code, Cursor или Codex массовую правку страниц и баз. Подходит там, где агент работает без человека: в CI, по расписанию, на собственном сервере.
Подходит, если
- Нужно переименовать или обновить десятки страниц одним пакетом, с безопасным повтором по ключу идемпотентности
- Агент ведет базу задач: отбирает строки по статусу и сроку, создает новые из шаблона и меняет свойства обычными значениями
- Страницу со спецификацией надо прочитать в Markdown, поправить заголовки и вернуть в Notion
- Агент запускается в CI или по расписанию и не может подтвердить вход в браузере
- К странице нужно прикрепить файл или показать модели картинку из Notion, например скриншот к баг-репорту
Не подходит, если
- Нужен чат с Notion в веб-версии claude.ai: для него автор советует размещенный коннектор самого Notion
- Нужны поддержка и гарантии от Notion: код написал сторонний автор, а не сама компания
- На машине нет Node.js 20 и новее: в Claude Desktop это обходит пакет `.mcpb`, в остальных клиентах понадобится Docker
- Администратор отключил личные токены, а подключать интеграцию к каждой нужной странице по отдельности некому
Пример запроса к агенту
Найди в базе «Задачи» все строки со статусом «В работе», у которых срок уже прошел, и пришли список со ссылками на страницыMCP
- Транспорт
- stdio, http
- Авторизация
- API-ключ
Переменные окружения
NOTION_TOKENобязательная, секрет- Личный токен (ntn_…) или секрет внутренней интеграции Notion
NOTION_PAGE_ID- Страница-родитель по умолчанию для создания страниц и баз
NOTION_READ_ONLY- Значение true отключает все операции записи
NOTION_ALLOWED_OPERATIONS- Список разрешенных операций или групп через запятую
NOTION_UPLOAD_ROOT- Папка, за пределы которой не выходит загрузка файлов по пути
Ограничения
- Сервер неофициальный: Notion к нему отношения не имеет.
- Личный токен действует год с момента создания и открывает все страницы, доступные вам. Администратор рабочего пространства может отключить такие токены и отозвать чужие.
- Права ограничиваются по операциям, а не по параметрам: `update_page_markdown` может заменить тело страницы, и блокировка группы `destructive` его не отключает. Запись целиком выключают значения `NOTION_READ_ONLY=true` или `NOTION_ALLOWED_OPERATIONS=read`.
- Запрос подтверждения перед опасными операциями (`NOTION_CONFIRM_DESTRUCTIVE`) работает только в клиентах с поддержкой запросов подтверждения, в остальных сервер отвечает `confirmation_unavailable`.
- Операция `upload_file` с источником `path` читает любой файл, доступный процессу сервера. Папку ограничивают переменной `NOTION_UPLOAD_ROOT`.
- В режиме HTTP каждый, кто достучится до `/mcp`, действует от имени токена, поэтому вне локального адреса обязателен `MCP_AUTH_TOKEN`.
Как отключить. Отзовите токен на странице app.notion.com/developers/tokens кнопкой Revoke: доступ пропадет сразу. Затем уберите сервер из настроек агента, в Claude Code командой `claude mcp remove notion -s user`.
Частые вопросы
Как подключить Notion MCP к Claude Code?
Получите токен на app.notion.com/developers/tokens и выполните `claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server`. Для нескольких клиентов сразу автор предлагает `npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here`: он находит установленных агентов и пишет их настройки. Без флага `--env` запись создается без токена, и сервер отвечает на каждый вызов ошибкой авторизации.
Чем Notion MCP на токене отличается от размещенного коннектора Notion?
Размещенный коннектор Notion входит через OAuth, и вход подтверждает человек. Этот сервер работает по токену, поэтому запускается в CI, по расписанию и на своем сервере. Для чата в веб-версии claude.ai автор советует коннектор Notion.
Какой токен выбрать, личный или внутренней интеграции?
Автор рекомендует личный токен: он видит все, что видите вы, и не требует отдельно подключать каждую страницу. Токен внутренней интеграции видит только страницы, к которым вы ее подключили через меню «Подключения». Он нужен, если администратор требует доступ по отдельным страницам. Большинство ошибок `object_not_found` возникает от токена интеграции, не подключенной к странице.
Как сделать Notion MCP только для чтения?
Задайте `NOTION_READ_ONLY=true` или `NOTION_ALLOWED_OPERATIONS=read`. Отключенные операции пропадают из перечня инструментов, а при отсутствии операций записи `notion_write` не объявляется вовсе. Можно оставить чтение и, например, `append_blocks` с `add_page_comment`: `NOTION_ALLOWED_OPERATIONS=read,append_blocks,add_page_comment`.
Как агент узнает параметры операции из 47?
Он вызывает `notion_describe` с именем операции и получает схему JSON и рабочий пример. Если вызов не прошел проверку, ответ сам содержит схему, пример и подсказку `fix`, поэтому исправить запрос можно за один шаг. В идентификаторы страниц и блоков можно подставлять ссылки из Notion.
Можно ли запустить Notion MCP по HTTP на своем сервере?
Да, задайте `MCP_TRANSPORT=http`, и сервер поднимет `/mcp` на порту 3000, по умолчанию на 127.0.0.1. Для адреса вне локального обязательно задайте `MCP_AUTH_TOKEN`, иначе доступ получит любой, кто до него достучится. Есть образ `ghcr.io/awkoy/notion-mcp-server:latest`. В образе по умолчанию запускается stdio, `HEALTHCHECK` не включен.
Работает ли сервер в Claude Desktop без Node.js?
Да, для этого есть пакет `notion-mcp-server.mcpb` из последнего релиза: его открывают двойным щелчком или перетаскивают в раздел расширений в настройках и вводят токен. Для тех, кто раньше не правил конфигурацию, в папке docs лежит пошаговое руководство.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыMCP-сервер для Notion: агент ищет, читает, запрашивает и обновляет страницы и базы рабочего пространства
Официальный локальный MCP-сервер для Notion API: поиск, чтение и правка страниц в Markdown, работа с базами данных
Официальный MCP сервер Anytype: агент ищет, создает и меняет объекты, списки и типы в вашей базе знаний
Obsidian MCP Server
obsidian-mcp-server
MCP-сервер для хранилища Obsidian: чтение, поиск и точечная правка заметок, разделов, frontmatter и тегов
Notion Plugin для Claude Code
Notion Plugin for Claude Code
Официальный плагин Notion для Claude Code: четыре скилла, десять команд и подключенный MCP-сервер за одну установку
MCP-сервер Trello на 57 инструментов: карточки, списки, чек-листы, вложения, комментарии, поля и рабочие пространства, плюс выгрузка критериев приемки
Сравнение с похожими
Записи с тем же главным запросом: чем они отличаются.
| Запись | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| Notion MCP (awkoy) (эта запись) | нет | API-ключ | 179 | |
| Notion MCP Server | да | API-ключ | 4 686 | официальный локальный сервер Notion: права сужаются в настройках интеграции, базы через него не удалить |
| Notion MCP Server | нет | API-ключ | 925 | сторонний сервер только по stdio с отдельными инструментами правки абзацев, заголовков, списков и блоков кода |
| AFFiNE MCP Server — заметки и базы AFFiNE для агента | нет | ключ необязателен | 315 | MCP-сервер для AFFiNE |
Коротко о README
В документации разобраны получение токена, установка одной командой через `add-mcp` и вручную для Claude Code, Cursor, VS Code, Gemini CLI, Claude Desktop и Docker, таблицы переменных окружения и группы операций для ограничения прав. Отдельно описаны режим HTTP с `MCP_AUTH_TOKEN`, загрузка файлов и разрешения по инструментам для Claude Code. В репозитории лежат сравнение с официальным сервером, замеры расхода токенов в папке `benchmarks`, история изменений, руководство по переходу с версий 1 и 2 и пошаговая инструкция для Claude Desktop.