notioncode_mcp

Локальный агентный мост между моделями Notion AI и популярными coding-окружениями: OpenCode, Claude Code и Codex CLI. Позволяет использовать модели Notion AI вместо стандартных OpenAI/Anthropic-моделей в этих инструментах — без подписки OpenAI или Anthropic.

Поддерживаемые модели:

• notion-fable/fable-5 (Fable 5, по умолчанию)

• notion-fable/gpt-5.6-sol (GPT-5.6 Sol)

Агент умеет читать, создавать и редактировать файлы под /root, выполнять shell-команды и запускать проверки.

Как это работает

Архитектура

  OpenCode / Claude Code / Codex CLI
           │
           │  HTTP (OpenAI или Anthropic API-формат)
           ▼
  notion-fable-proxy  (127.0.0.1:8765)
           │
           │  Агентный цикл — запросы к Notion AI
           ▼
     Notion AI Models
      (fable-5 / gpt-5.6-sol)
           │
           │  MCP-вызовы инструментов
           ▼
  notion-code-mcp  (127.0.0.1:8787)
  list_files · read_file · write_file · edit_file · run_shell

1. notion-fable-proxy — API-прокси на порту 8765. Принимает запросы в формате OpenAI (для OpenCode, Codex CLI) или Anthropic Messages API (для Claude Code) и перенаправляет их к моделям Notion AI, выполняя агентный цикл.

2. notion-code-mcp — локальный MCP-сервер на порту 8787. Предоставляет агенту инструменты для работы с файловой системой и выполнения shell-команд.

3. notion-private-api-mcp — опциональный MCP для чтения и редактирования Notion-страниц напрямую через token_v2.

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

notioncode_mcp/
├── bridge/                   # API-прокси и агентный цикл
├── runtime/                  # Локальный MCP-сервер (list_files, read_file, ...)
├── notion-private-api-mcp/   # MCP для Notion Private API (token_v2)
├── config/                   # Конфигурации для OpenCode, Claude Code, VS Code, Codex CLI
├── browser/                  # Запуск Chrome + Xvfb + noVNC для авторизации Notion
├── deploy/systemd/           # systemd-юниты для автозапуска сервисов
├── scripts/install-local.sh  # Установщик
├── bin/codex                 # Обёртка над Codex CLI с изолированным CODEX_HOME
└── requirements.txt          # Python-зависимости для bridge

Каталоги .runtime/, state/, node_modules/ и runtime/.env не публикуются. В них хранятся: Python venv, браузерный профиль Notion, token_v2, история сессий, SQLite-базы Codex CLI, локальный секрет MCP.

Related MCP server: Herald

Требования

• Ubuntu-сервер (проверено на Ubuntu 22.04/24.04)

• Python 3.10+

• Node.js 18+

• npm

• openssl (для генерации MCP-секрета)

• Аккаунт Notion с доступом к моделям Fable 5 / GPT-5.6 Sol

• Установленный OpenCode (opencode), Claude Code (claude) или Codex CLI — в зависимости от нужного клиента

Установка

1. Клонировать репозиторий

git clone <repo-url> /root/notioncode_mcp
cd /root/notioncode_mcp

2. Запустить установщик

chmod +x scripts/install-local.sh
sudo scripts/install-local.sh

Установщик выполняет:

• Создаёт Python venv в .runtime/notion-agent-cli-venv и устанавливает зависимости из requirements.txt

• Устанавливает npm-зависимости для runtime/ и notion-private-api-mcp/

• Генерирует runtime/.env с MCP_PATH_SECRET (случайный hex-секрет), CODE_ROOT=/root, PORT=8787

• Создаёт симлинки: .notionagents, notion-gui-profile, venv, конфиги OpenCode, Claude Code, VS Code Remote

• Устанавливает и активирует systemd-юниты notion-code-mcp и notion-fable-proxy

• Создаёт /usr/local/bin/codex → bin/codex

3. Авторизовать Notion

После установки необходимо передать token_v2 из вашего аккаунта Notion.

Способ A — вручную: Скопируйте token_v2 из cookie браузера (DevTools → Application → Cookies → token_v2) и запишите его в файл учётной записи в state/notionagents/ согласно формату, ожидаемому notion-agent-cli.

Способ B — через браузер (noVNC):

# Запустить Chrome с noVNC для визуальной авторизации
bash browser/start.sh
# Открыть в браузере: http://<server-ip>:6080
# Войти в Notion, после чего token_v2 будет сохранён автоматически

Проверка установки

# Статус сервисов
systemctl status notion-code-mcp notion-fable-proxy

# Проверка API-прокси
curl http://127.0.0.1:8765/healthz

# Проверка Codex CLI
codex --version
codex mcp list

Использование

OpenCode

cd /root/your-project
opencode

Fable 5 выбран по умолчанию. Для GPT-5.6 Sol:

opencode run --model notion-fable/gpt-5.6-sol "Выполни задачу"

OpenCode обращается к http://127.0.0.1:8765 как к OpenAI-совместимому API. Конфигурация находится в config/opencode.jsonc, симлинк установлен в ~/.config/opencode/opencode.jsonc.

Claude Code (VS Code)

1. Установите расширение anthropic.claude-code в VS Code.

2. Выполните команду Developer: Reload Window.

3. Расширение автоматически использует ANTHROPIC_BASE_URL=http://127.0.0.1:8765, логин Anthropic не нужен.

Fable 5 выбран по умолчанию. Для смены модели:

• В чате Claude Code введите /model и выберите GPT-5.6 Sol (Notion)

• Или запустите в терминале:

claude --model fable-5
claude --model gpt-5.6-sol

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

Конфигурация расширения: config/claude-settings.json → симлинк ~/.claude/settings.json.

Codex CLI

Терминальная команда codex запускается через bin/codex с изолированным CODEX_HOME в state/codex-cli/.

# Запустить с Fable 5 (по умолчанию)
codex

# Запустить с GPT-5.6 Sol
codex -m gpt-5.6-sol

# Одноразовая задача
codex run "Выполни задачу"

# Список подключённых MCP
codex mcp list

В этом профиле доступен нативный /goal Codex и подключён notion-private MCP для работы с Notion-страницами.

Изоляция: Codex CLI в этом профиле полностью изолирован от расширения VS Code (openai.chatgpt). Расширение VS Code использует /root/.codex и оригинальные модели OpenAI — wrapper на него не влияет.

Конфигурация: config/codex-cli-config.toml → копируется в state/codex-cli/config.toml при первой установке.

Системные сервисы

Два systemd-юнита запускаются автоматически при старте системы:

# Перезапустить сервисы
systemctl restart notion-code-mcp notion-fable-proxy

# Посмотреть логи
journalctl -u notion-fable-proxy -f
journalctl -u notion-code-mcp -f

Управление моделями

Список доступных моделей и их маппинг описаны в config/codex-models.json. Добавление новой модели:

1. Добавьте запись в config/codex-models.json.

2. Перезапустите notion-fable-proxy.

Как работает интеграция с Notion AI

Проект использует обычный Notion AI — не Custom Agent, а стандартный AI-чат, доступный в любом Notion-воркспейсе. Взаимодействие происходит через — Python-библиотеку, которая авторизуется через (cookie вашей сессии) и отправляет запросы к внутреннему API Notion AI.

Как именно это работает

Режимы работы

Planner mode (используется в OpenCode и Codex CLI без ):

• Модели отправляется специальный system-промпт: она выступает как «coding planner», который не выполняет действия сам, а рекомендует ровно одно действие за раз в виде JSON.

• Пример:

• Bridge выполняет действие через MCP-рантайм, возвращает результат модели в том же треде.

• Цикл повторяется до тех пор, пока модель не вернёт (максимум 20 шагов).

Workflow mode (используется при заданном ):

• Модель работает как нативный Notion-агент с воркфлоу, сама эмитирует вызовы инструментов в формате .

• Bridge перехватывает такие вызовы, выполняет их через MCP и продолжает тред (, ).

Streaming mode (без инструментов, например в чате):

• Модель отвечает напрямую, дельты текста стримятся клиенту через SSE.

Аутентификация и сессия

• Авторизация происходит через — cookie вашей браузерной сессии Notion.

• читает аккаунт из (симлинк на ).

• сохраняется между шагами цикла, поэтому модель «помнит» контекст предыдущих действий внутри одной задачи.

• Каждый новый запрос от клиента начинает новый тред.

Важные ограничения

• Используется неофициальный внутренний API Notion — он может измениться без предупреждения.

• и в режиме планировщика отключены, чтобы модель фокусировалась на локальных файлах.

• Максимальная глубина цикла инструментов: 20 шагов (planner mode) / 12 шагов (workflow mode).

Безопасность

Coding runtime слушает только 127.0.0.1. Не публикуйте runtime/.env, state/, браузерный профиль и Notion cookie. Приватный API Notion неофициальный и может измениться без предупреждения.

Устранение неполадок

Сервис не запускается:

journalctl -u notion-fable-proxy --no-pager -n 50

Убедитесь, что Python venv существует: .runtime/notion-agent-cli-venv/bin/python.

Ошибка авторизации Notion: Запустите браузерный поток через browser/start.sh и повторно авторизуйтесь в Notion.

codex не найден:

ls -la /usr/local/bin/codex
# Должен быть симлинк на /root/notioncode_mcp/bin/codex
sudo ln -sfn /root/notioncode_mcp/bin/codex /usr/local/bin/codex

MCP не подключается:

curl http://127.0.0.1:8787/  # notion-code-mcp
codex mcp list               # проверить список серверов

Установка на Windows через OpenCode

После регистрации в https://app.notion.com/ и оформления подписки скачайте notioncode_mcp_v2.tar.gz в отдельную папку.

Если нет доступа к ИИ, установите OpenCode: там есть бесплатный почти безлимитный DeepSeek V4 Flash. Важно: ставим через командную строку, НЕ расширением VS Code. Если не знаете как — спросите любой ИИ: «как установить opencode на Windows».

Важно для РФ: всё работает только через VPN. Можно использовать @sonnetvpn_bot или https://sonnet.website/

Установка MCP-сервера

1. Откройте OpenCode в командной строке. Можно через cmd в папке проекта, но удобнее через VS Code с открытой папкой, где лежит notioncode_mcp_v2.tar.gz. Скриншот 1.

2. Через /models выберите DeepSeek V4 Flash Free. Если спросит thinking — Max. Скриншот 2.

3. Через @ выберите notioncode_mcp_v2.tar.gz и отправьте:

@notioncode_mcp_v2.tar.gz распакуй этот архив в этой папке

Архив распакуется в текущей папке. Скриншот 3.

4. Отправьте:

изучи этот mcp-сервер, подробный анализ, без него файлы не меняй. Пойми принцип работы, его менять нельзя! Этот mcp сделан для linux
После подробного анализа адаптируй его точь-в-точь с теми же принципами работы под windows

Ждите завершения. Должно получиться как на скриншоте 4.

5. Установите Codex CLI:

установи codex cli. mcp-сервер пока не устанавливай

Если OpenCode просит разрешения — давайте все, Always Allow. Скриншот 5.

6. Проверьте Codex CLI: в отдельном терминале напишите codex и Enter. Должен открыться интерфейс Codex с вариантами входа. Скриншот 6. Сразу закройте через Ctrl+C или Ctrl+Z. Если Codex уже был установлен и спросит про доверие к папке/workspace — ничего не настраиваем, просто закрываем.

7. Вернитесь в OpenCode и отправьте:

теперь установи этот mcp-сервер, но пока не подключай к codex

Ждите установки. В конце должно быть как на скриншоте 7.

8. Отправьте:

теперь изучи какие данные от сессии (прим. token_v2) необходимы для работы этого mcp-сервера. После этого запусти браузерную страницу https://app.notion.com/ в которой я залогинюсь и после попрошу снять с неё cookie и подкинуть в mcp-сервер

OpenCode сам откроет https://app.notion.com/. Залогиньтесь в аккаунт с подпиской из прошлого поста.

9. После входа отправьте:

я зашёл, сними необходимые cookie и подкинь в mcp-сервер. После этого подключи codex к этому mcp-серверу постоянно, а не для одной сессии

Ждите завершения. Должно получиться как на скриншоте 8. Если напишет «Для работы нужно сначала запустить сервисы…» — отправьте:

запусти сам

10. Запустите Codex в соседнем терминале командой codex. Можно вместе с расширением Codex в VS Code; с отдельным приложением, думаю, тоже работает, но я не проверял. Если попросит разрешения или спросит про sandbox — давайте полный доступ, не только от администратора.

Если появится ошибка вроде:

⚠ MCP client for `notion-private` failed to start: MCP startup failed: Синтаксическая ошибка в имени файла, имени папки или метке тома. (os error 123)
⚠ MCP startup incomplete (failed: notion-private)

или похожая — игнорируйте, это «нормально».

После запуска напишите Codex: привет. Если ответ пришёл — отлично. Потом отправьте:

создай .py калькулятор в этой папке

При успешной настройке появится calculator.py. Скриншот 9.

11. Готово! Теперь можно пользоваться Codex в любом проекте/папке. Это полноценный Codex, как если бы у вас были максимальные подписки. OpenCode и лишние окна можно закрыть — всё продолжит работать.

Если нужно всё удалить: откройте OpenCode, через /sessions найдите чат настройки MCP-сервера и отправьте:

теперь удали этот mcp-сервер и его связь с codex

Как пользоваться

• Модели меняются через /model в Codex CLI или в расширении рядом с кнопкой отправки; там же регулируется thinking.

• Несколько чатов одновременно, особенно через /goal, запускать не советую: высокая вероятность ошибки 502.

Лимитов, квот и ограничений нет — всё полностью безлимитно.

Приятного пользования! Если будут вопросы — задавайте в комментариях.