Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Сервер Notion MCP

[!NOTE]

Для наилучшего опыта используйте Remote Notion MCP — наш официальный размещённый MCP-сервер. Этот репозиторий представляет собой отдельную, самостоятельно размещённую реализацию MCP-сервера, которая больше не поддерживается активно. Пожалуйста, используйте Remote Notion MCP вместо него. Он специально создан, чтобы предоставлять AI-агентам более быстрые результаты, используя значительно меньше токенов.

Remote Notion MCP может выполнять семантический поиск по вашему рабочему пространству и подключённым приложениям, читать и редактировать страницы в Markdown, а также возвращать только наиболее релевантный контекст. Это означает меньше времени ожидания, меньше использования контекстного окна и более низкие затраты на токены. Он также использует OAuth и автоматически учитывает существующие разрешения Notion каждого пользователя — без API-токенов, JSON-конфигурации, ручного предоставления доступа к страницам или необходимости поддерживать локальный сервер.

Возможность	Remote Notion MCP	Этот проект (локальный)
Быстрый размещённый опыт	✅	Запускается и обновляется локально
Эффективные по токенам ответы	✅	Ограниченно
Мощные инструменты, адаптированные для AI-агентов	✅	Базовые инструменты на основе API
Семантический поиск по вашему рабочему пространству Notion	✅	Только поиск по ключевым словам
Поиск через AI Connector по подключённым приложениям	✅	Недоступно
Чтение и редактирование страниц в формате Markdown	✅	Ограничено двумя инструментами для содержимого страниц
Простая настройка через OAuth	✅	Ручная настройка токена и JSON
Учитывает существующие разрешения Notion каждого пользователя	✅	Ручные разрешения интеграции и предоставление доступа к страницам
Активная поддержка и постоянные улучшения	✅	Не поддерживается активно

Узнайте больше и начните работу в документации Remote Notion MCP.

Мы уделяем приоритетное внимание и предоставляем активную поддержку только для Remote Notion MCP. В результате:

• В будущем мы можем прекратить поддержку этого локального репозитория MCP-сервера.
• Проблемы и pull request'ы здесь не отслеживаются активно.
• Пожалуйста, не создавайте проблемы, связанные с удалённым MCP, здесь; вместо этого обратитесь в службу поддержки Notion.

Этот проект реализует MCP-сервер для Notion API.

---

⚠️ Критические изменения в версии 2.0.0

Версия 2.0.0 переходит на Notion API 2025-09-03, который вводит источники данных как основную абстракцию для баз данных.

Что изменилось

Удалённые инструменты (3):

• post-database-query — заменён на query-data-source
• update-a-database — заменён на update-a-data-source
• create-a-database — заменён на create-a-data-source

Новые инструменты (7):

• query-data-source — Запрос к источнику данных (базе данных) с фильтрами и сортировкой
• retrieve-a-data-source — Получение метаданных и схемы источника данных
• update-a-data-source — Обновление свойств источника данных
• create-a-data-source — Создание нового источника данных
• list-data-source-templates — Список доступных шаблонов в источнике данных
• move-page — Перемещение страницы в другое родительское расположение
• retrieve-a-database — Получение метаданных базы данных, включая её ID источников данных

Изменения параметров:

• Все операции с базами данных теперь используют data_source_id вместо database_id
• Значения фильтра поиска изменены с ["page", "database"] на ["page", "data_source"]
• Создание страницы теперь поддерживает оба родителя: page_id и database_id (для источников данных)

Нужно ли мне мигрировать?

Изменения кода не требуются. Инструменты MCP обнаруживаются автоматически при запуске сервера. При обновлении до v2.0.0 AI-клиенты автоматически увидят новые имена инструментов и параметры. Старые инструменты для баз данных больше недоступны.

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

Старый инструмент (v1.x)	Новый инструмент (v2.0)	Изменение параметра
post-database-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	Без изменений (использует parent.page_id)

Примечание: retrieve-a-database по-прежнему доступен и возвращает метаданные базы данных, включая список ID источников данных. Используйте retrieve-a-data-source, чтобы получить схему и свойства конкретного источника данных.

Всего инструментов теперь: 22 (было 19 в v1.x)

---

Содержимое страницы в формате Markdown

Сервер предоставляет два инструмента для работы с содержимым страниц в виде расширенного Markdown вместо JSON-блоков, что значительно эффективнее по токенам для AI-агентов:

• retrieve-page-markdown — Чтение полного содержимого страницы в формате Markdown (GET /v1/pages/{page_id}/markdown). Передайте include_transcript: true, чтобы встроить транскрипты заметок встреч.
• update-page-markdown — Редактирование содержимого страницы с помощью Markdown (PATCH /v1/pages/{page_id}/markdown). Предпочтительно использовать replace_content для перезаписи всей страницы или update_content для точечных замен по поиску и замене.

Эти конечные точки требуют версии Notion API 2026-03-11. Сервер теперь получает заголовок Notion-Version для каждой операции из спецификации OpenAPI, поэтому эти инструменты используют 2026-03-11, в то время как остальная часть API продолжает использовать 2025-09-03 — настройка не требуется. Если вы установите Notion-Version самостоятельно через OPENAPI_MCP_HEADERS, ваше значение будет иметь приоритет для каждого инструмента.

---

Установка

1. Настройка интеграции в Notion

Перейдите на https://www.notion.so/profile/integrations и создайте новую внутреннюю интеграцию или выберите существующую.

Хотя мы ограничиваем область действия Notion API (например, вы не сможете удалять базы данных через MCP), существует ненулевой риск для данных рабочего пространства при их передаче LLM. Пользователи, заботящиеся о безопасности, могут дополнительно настроить Возможности интеграции.

Например, вы можете создать токен интеграции только для чтения, предоставив только доступ «Чтение содержимого» на вкладке «Конфигурация»:

2. Подключение содержимого к интеграции

Убедитесь, что соответствующие страницы и базы данных подключены к вашей интеграции.

Для этого посетите вкладку Доступ в настройках вашей внутренней интеграции. Измените доступ и выберите страницы, которые вы хотите использовать.

В качестве альтернативы вы можете предоставить доступ к страницам по отдельности. Вам нужно посетить целевую страницу, нажать на три точки и выбрать «Подключить к интеграции».

3. Добавление конфигурации MCP в ваш клиент

С использованием npm

Cursor и Claude

Добавьте следующее в ваш .cursor/mcp.json или claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Вариант 1: Использование NOTION_TOKEN (рекомендуется)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Вариант 2: Использование OPENAPI_MCP_HEADERS (для продвинутых случаев)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

Добавьте следующее в ваш settings.json

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

Используйте Copilot CLI для интерактивного добавления MCP-сервера:

/mcp add

В качестве альтернативы создайте или отредактируйте файл конфигурации ~/.copilot/mcp-config.json и добавьте:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Для получения дополнительной информации см. документацию Copilot CLI.

С использованием Docker

Есть два варианта запуска MCP-сервера с Docker:

Вариант 1: Использование официального образа Docker Hub

Добавьте следующее в ваш .cursor/mcp.json или claude_desktop_config.json

Использование NOTION_TOKEN (рекомендуется):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Использование OPENAPI_MCP_HEADERS (для продвинутых случаев):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

Этот подход:

• Использует официальный образ Docker Hub
• Правильно обрабатывает экранирование JSON через переменные окружения
• Обеспечивает более надёжный метод конфигурации

Вариант 2: Сборка Docker-образа локально

Вы также можете собрать и запустить Docker-образ локально. Сначала соберите Docker-образ:

docker compose build

Затем добавьте следующее в ваш .cursor/mcp.json или claude_desktop_config.json

Использование NOTION_TOKEN (рекомендуется):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

Использование OPENAPI_MCP_HEADERS (для продвинутых случаев):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

Не забудьте заменить ntn_**** на ваш секрет интеграции. Найдите его на вкладке конфигурации вашей интеграции:

Варианты транспорта

Сервер Notion MCP поддерживает два режима транспорта:

Транспорт STDIO (по умолчанию)

Режим транспорта по умолчанию использует стандартный ввод/вывод для связи. Это стандартный транспорт MCP, используемый большинством клиентов, таких как Claude Desktop.

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

Потоковый HTTP-транспорт

Для веб-приложений или клиентов, предпочитающих HTTP-связь, вы можете использовать потоковый HTTP-транспорт:

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

При использовании потокового HTTP-транспорта сервер будет доступен по адресу http://127.0.0.1:<port>/mcp по умолчанию.

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

Потоковый HTTP-транспорт требует аутентификации с помощью bearer-токена для безопасности. У вас есть три варианта:

Вариант 1: Автоматически сгенерированный токен (только для разработки)

npx @notionhq/notion-mcp-server --transport http

Сервер сгенерирует безопасный случайный токен и запишет его в файл с ограниченными правами доступа:

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

Вариант 2: Пользовательский токен через командную строку (рекомендуется для продакшена)

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Вариант 3: Пользовательский токен через переменную окружения (рекомендуется для продакшена)

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

Аргумент командной строки --auth-token имеет приоритет над переменной окружения AUTH_TOKEN, если указаны оба.

Небезопасный вариант: отключение HTTP-аутентификации

Вы можете отключить аутентификацию bearer-токена только с помощью явного небезопасного флага:

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

ПРЕДУПРЕЖДЕНИЕ: --unsafe-disable-auth небезопасен. Сервер может быть доступен страницам, которые вы посещаете, через DNS rebinding. Используйте его только в изолированной сети.

Когда аутентификация отключена, сервер включает защиту от DNS rebinding, проверяя заголовки Host и Origin на соответствие настроенному локальному хосту и loopback-хостам. Предыдущий флаг --disable-auth по-прежнему принимается как устаревший псевдоним, но будет выводить предупреждение.

Выполнение HTTP-запросов

Все запросы к потоковому HTTP-транспорту должны включать bearer-токен в заголовке Authorization:

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Примечание: Убедитесь, что вы установили либо переменную окружения NOTION_TOKEN (рекомендуется), либо переменную окружения OPENAPI_MCP_HEADERS с вашим токеном интеграции Notion при использовании любого режима транспорта.

Обслуживание нескольких интеграций (передача токена на каждый запрос)

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

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

Затем клиенты отправляют свой токен Notion в запросе initialize, используя специальный заголовок Notion-Token:

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Как разрешается токен для каждого соединения, по порядку:

1. Заголовок Notion-Token (предпочтительно — однозначен и работает вместе с собственной аутентификацией Authorization сервера). Если он присутствует, он должен быть действительным токеном Notion, иначе запрос отклоняется с 401.
2. Authorization: Bearer ntn_**** — только когда собственная bearer-аутентификация сервера отключена (--unsafe-disable-auth), чтобы заголовок мог свободно нести токен Notion напрямую.
3. В противном случае токен окружения при запуске (NOTION_TOKEN / OPENAPI_MCP_HEADERS), если он установлен, чтобы передача токена и интеграция по умолчанию могли сосуществовать в одном развёртывании.

Примечания:

• Только значения с префиксом токена Notion (ntn_, устаревший secret_) рассматриваются как токены Notion, поэтому секрет шлюза сервера и токен Notion клиента никогда не конфликтуют.
• Каждый токен привязан к своей MCP-сессии; токены никогда не регистрируются (выводится только отредактированный префикс).
• Это намеренная настройка передачи токена. Всегда развёртывайте её через TLS и предпочитайте оставлять собственную bearer-аутентификацию сервера (--auth-token) включённой в качестве шлюза перед трафиком с несколькими арендаторами.

Примеры

1. Используя следующую инструкцию

Comment "Hello MCP" on page "Getting started"

AI правильно спланирует два вызова API, v1/search и v1/comments, для выполнения задачи

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

Add a page titled "Notion MCP" to page "Development"

1. Вы также можете ссылаться непосредственно на ID содержимого

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Разработка

Сборка и тестирование

npm run build
npm test

Запуск

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Тестирование изменений локально в Cursor:

1. Выполните команду npm link из корня репозитория, чтобы создать глобальную символьную ссылку на пакет notion-mcp-server.
2. Вставьте приведённый ниже фрагмент конфигурации в mcp.json Cursor (или другой MCP-клиент, с которым вы хотите протестировать).
3. (Очистка) выполните npm unlink из корня репозитория.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Публикация

npm login
npm publish --access public