Notion MCP

Notion MCP Server

[!NOTE]

Мы представили Notion MCP, удаленный MCP-сервер со следующими улучшениями:

• Простая установка через стандартный OAuth. Больше не нужно возиться с JSON или API-токенами.
• Мощные инструменты, адаптированные для AI-агентов, включая редактирование страниц в Markdown. Эти инструменты разработаны с учетом оптимизированного потребления токенов.

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

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

• В будущем мы можем закрыть этот репозиторий локального MCP-сервера.
• Issues и pull requests здесь активно не отслеживаются.
• Пожалуйста, не сообщайте здесь о проблемах, связанных с удаленным 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 (было 19 в версии 1.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 точки и выбрать «Подключить к интеграции».

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 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

Потоковый 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-транспорт требует аутентификации по токену-носителю для безопасности. У вас есть три варианта:

Вариант 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-аутентификации

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

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

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

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

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

Все запросы к потоковому HTTP-транспорту должны включать токен-носитель в заголовок 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_**** — только когда собственная аутентификация по токену-носителю сервера отключена (--unsafe-disable-auth), поэтому заголовок свободен для прямой передачи токена Notion.
3. В противном случае используется токен окружения запуска (NOTION_TOKEN / OPENAPI_MCP_HEADERS), если он установлен, так что сквозная передача и интеграция по умолчанию могут сосуществовать в одном экземпляре.

Примечания:

• Только значения с префиксом токена Notion (ntn_, устаревший secret_) рассматриваются как токены Notion, поэтому секрет шлюза сервера и токен Notion арендатора никогда не конфликтуют.
• Каждый токен привязан к своей MCP-сессии; токены никогда не логируются (выводится только сокращенный префикс).
• Это преднамеренная настройка сквозной передачи токена. Всегда развертывайте ее через TLS и предпочитайте держать собственную аутентификацию по токену-носителю сервера (--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. Вы также можете напрямую ссылаться на идентификатор контента

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