Notion MCP Server

Примечание

Для оптимальной работы используйте Remote Notion MCP —

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

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

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

Подробнее о Remote Notion MCP и начале работы читайте в документации Remote Notion MCP.

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

В будущем мы можем прекратить поддержку этого репозитория локального MCP-сервера.
Мы не отслеживаем здесь вопросы и pull request.
Не создавайте здесь обращения по Remote Notion 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 — возвращает метаданные базы данных, включая идентификаторы её источников данных

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

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

Нужно ли выполнять миграцию?

Изменения в коде не требуются. MCP-инструменты обнаруживаются автоматически при запуске сервера. После обновления до версии 2.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 по-прежнему доступен и возвращает метаданные базы данных, в том числе список идентификаторов её источников данных. Чтобы получить схему и свойства конкретного источника данных, используйте retrieve-a-data-source.

Теперь доступно 22 инструмента (в v1.x было 19).

Содержимое страниц в 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 доступ к данным рабочего пространства, вы подвергаете их определённому риску. Если безопасность для вас особенно важна, настройте возможности интеграции дополнительно.

Например, чтобы создать токен интеграции только для чтения, на вкладке "Configuration" предоставьте доступ только к "Read content":

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

Предоставьте интеграции доступ к нужным страницам и базам данных.

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

Можно также предоставить доступ к страницам по отдельности. Откройте нужную страницу, нажмите на три точки и выберите "Connect to integration".

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

Добавьте MCP-сервер с помощью интерактивной команды Copilot CLI:

/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 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 Server поддерживает два режима транспорта:

Транспорт 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

Транспорт Streamable HTTP

Для веб-приложений и клиентов, которым удобнее взаимодействовать по HTTP, можно использовать транспорт Streamable 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"

По умолчанию сервер с транспортом Streamable HTTP будет доступен по адресу http://127.0.0.1:/mcp.

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

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

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

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

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

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

Вариант 2: собственный токен через командную строку (рекомендуется для production)

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

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

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-запросов

Во всех запросах к транспорту Streamable 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:

"
-H "Notion-Token: ntn_****"
-H "Content-Type: application/json"
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}'
http://localhost:3000/mcp">

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

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

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

Примечания:

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

Примеры

При использовании следующей инструкции

Comment "Hello MCP" on page "Getting started"

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

Аналогично, следующая инструкция создаст новую страницу с названием "Notion MCP" внутри родительской страницы "Development":

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

Также можно напрямую указать 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:

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

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

Публикация

npm login
npm publish --access public