Neon

Neon MCP Server

Neon MCP Server — это инструмент с открытым исходным кодом, который позволяет взаимодействовать с вашими базами данных Lakebase Postgres на Neon на естественном языке.

Протокол контекста модели (MCP) — это стандартизированный протокол, предназначенный для управления контекстом между большими языковыми моделями (LLM) и внешними системами. Этот репозиторий предоставляет удалённый MCP-сервер для Neon.

MCP-сервер Neon действует как мост между запросами на естественном языке и Neon API. Построенный на основе MCP, он преобразует ваши запросы в необходимые вызовы API, позволяя вам управлять такими задачами, как создание проектов и веток, выполнение запросов и проведение миграций баз данных без усилий.

Некоторые ключевые возможности Neon MCP server включают:

• Взаимодействие на естественном языке: Управляйте базами данных Neon с помощью интуитивно понятных разговорных команд.
• Упрощённое управление базами данных: Выполняйте сложные действия без написания SQL или прямого использования Neon API.
• Доступность для неразработчиков: Дайте пользователям с разным техническим уровнем возможность взаимодействовать с базами данных Neon.
• Поддержка миграций баз данных: Используйте возможности ветвления Neon для изменений схемы базы данных, инициированных на естественном языке.

Например, в Claude Code или любом MCP-клиенте вы можете использовать естественный язык для выполнения задач с Neon, таких как:

• Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
• I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
• Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Вопросы безопасности Neon MCP Server
Neon MCP Server предоставляет мощные возможности управления базами данных через запросы на естественном языке. Всегда проверяйте и авторизуйте действия, запрашиваемые LLM, перед выполнением. Убедитесь, что только авторизованные пользователи и приложения имеют доступ к Neon MCP Server.

Neon MCP Server предназначен только для локальной разработки и интеграций с IDE. Мы не рекомендуем использовать Neon MCP Server в производственных средах. Он может выполнять мощные операции, которые могут привести к случайным или несанкционированным изменениям.

Для получения дополнительной информации см. Руководство по безопасности MCP →.

Настройка Neon MCP Server

Существует несколько вариантов настройки Neon MCP Server:

1. Быстрая настройка с API-ключом (Cursor, VS Code и Claude Code): Выполните neon@latest init, чтобы автоматически настроить MCP-сервер Neon, навыки агента и расширение VS Code одной командой.
2. Удалённый MCP-сервер (аутентификация на основе OAuth): Подключитесь к управляемому MCP-серверу Neon, используя OAuth для аутентификации. Этот метод более удобен, поскольку устраняет необходимость управления API-ключами. Кроме того, вы автоматически получите последние функции и улучшения сразу после их выпуска.
3. Удалённый MCP-сервер (аутентификация на основе API-ключа): Подключитесь к управляемому MCP-серверу Neon, используя API-ключ для аутентификации. Этот метод полезен, если вы хотите подключить удалённого агента к Neon там, где OAuth недоступен. Кроме того, вы автоматически получите последние функции и улучшения сразу после их выпуска.

Предварительные требования

• Приложение MCP-клиента.
• Учётная запись Neon.
• Node.js (>= v18.0.0): Скачайте с nodejs.org.
• Если включён IP Allow, добавьте 34.192.103.46 и 23.22.233.166 в свой список разрешений (mcp.neon.tech статические IP-адреса).

Для разработки вам понадобится Node.js 22+ (pnpm предоставляется через Corepack — выполните corepack enable, чтобы активировать его).

Вариант 1. Быстрая настройка с API-ключом

Не хотите создавать API-ключ вручную?

Выполните neon@latest init, чтобы автоматически настроить MCP-сервер Neon одной командой:

npx neon@latest init

Это работает с Cursor, VS Code (GitHub Copilot) и Claude Code. Он выполнит аутентификацию через OAuth, создаст для вас API-ключ Neon и автоматически настроит ваш редактор.

Вариант 2. Удалённый размещённый MCP-сервер (аутентификация на основе OAuth)

Подключитесь к управляемому MCP-серверу Neon, используя OAuth для аутентификации. Это самая простая настройка, не требующая локальной установки этого сервера и настройки API-ключа Neon в клиенте.

Выполните следующую команду, чтобы добавить Neon MCP Server для всех обнаруженных агентов и редакторов в вашем рабочем пространстве:

npx add-mcp https://mcp.neon.tech/mcp

Добавьте флаг -g, чтобы добавить Neon MCP Server в глобальный список MCP-серверов вместо ограничения проектом.

В качестве альтернативы вы можете добавить следующую запись «Neon» в файл конфигурации MCP-сервера вашего клиента (например, mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Добавьте следующее в файл конфигурации Kiro MCP (~/.kiro/settings/mcp.json для глобального, или .kiro/settings/mcp.json для ограниченного проектом):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Или используйте кнопку установки в один клик в верхней части этого README. Для получения дополнительной информации см. документацию Kiro MCP.

• Перезапустите или обновите ваш MCP-клиент.
• В вашем браузере откроется окно OAuth. Следуйте подсказкам, чтобы авторизовать ваш MCP-клиент для доступа к вашей учётной записи Neon.

При аутентификации на основе OAuth MCP-сервер по умолчанию будет работать с проектами в вашей личной учётной записи Neon. Чтобы получить доступ к проектам организации или управлять ими, вы должны явно указать либо org_id, либо project_id в вашем запросе к MCP-клиенту.

Вариант 3. Удалённый размещённый MCP-сервер (аутентификация на основе API-ключа)

Удалённый MCP-сервер также поддерживает аутентификацию с использованием API-ключа в заголовке Authorization, если ваш клиент это поддерживает.

Создайте API-ключ Neon в консоли Neon. Затем выполните следующую команду, чтобы добавить Neon MCP Server для всех обнаруженных агентов и редакторов в вашем рабочем пространстве:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

В качестве альтернативы вы можете добавить следующую запись «Neon» в файл конфигурации MCP-сервера вашего клиента (например, mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Укажите API-ключ организации, чтобы ограничить доступ только проектами организации.

Области действия и режим только для чтения

Neon MCP поддерживает области OAuth read, write и * (* означает обе). Ваш MCP-клиент может запрашивать эти области напрямую или выбрать их в интерфейсе разрешений OAuth.

Режим только для чтения ограничивает доступные инструменты, отключая операции записи, такие как создание проектов, веток или выполнение миграций. Инструменты только для чтения включают просмотр списка проектов, описание схем, запросы данных и просмотр метрик производительности.

Вы можете установить режим только для чтения двумя способами:

1. Выбор области OAuth (рекомендуется): В OAuth выберите режим только для чтения, сняв флажок Полный доступ в интерфейсе авторизации.
2. Параметр запроса readonly: Добавьте ?readonly=true к URL вашего MCP-сервера:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

Как ведёт себя параметр запроса:

• Поток с API-ключом: readonly=true — это способ включить режим только для чтения (в этом потоке нет обмена областями OAuth).
• Поток OAuth: readonly=true переопределяет область OAuth. Без него режим только для чтения определяется областью, выбранной в интерфейсе согласия OAuth.

Устаревший HTTP-заголовок x-read-only также поддерживается как запасной вариант (с более низким приоритетом, чем параметр запроса).

Примечание: Режим только для чтения ограничивает доступные инструменты. Кроме того, инструмент run_sql остаётся доступным только для запросов на чтение.

Параметры запроса URL для контроля доступа

Контекст предоставления прав (категории областей, ограничение проектов, режим только для чтения) настраивается через параметры запроса URL на URL MCP-сервера. Конфигурация передаётся с каждым запросом и вступает в силу немедленно — повторная авторизация не требуется.

Параметр	Описание	Пример
readonly	Включить режим только для чтения (true/false)	?readonly=true
category	Ограничить конкретными категориями инструментов (повторяющиеся или CSV)	?category=querying&category=schema
projectId	Ограничить все операции одним проектом	?projectId=proj-123

Пример: режим только для чтения + ограничение проекта:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

Пример с фильтрацией по категориям (только инструменты запросов и схем):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

Вы можете просмотреть, какие инструменты видны для любой конфигурации, используя конечную точку /api/list-tools (авторизация не требуется):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

Инструменты, доступные в режиме только для чтения

• list_projects, list_shared_projects, describe_project, list_organizations
• describe_branch, list_branch_computes, compare_database_schema
• run_sql, run_sql_transaction, get_database_tables, describe_table_schema
• list_slow_queries, explain_sql_statement, inspect_database
• get_connection_string
• get_neon_auth_config
• query_logs, list_log_fields, list_log_field_values
• search, fetch, list_docs_resources, get_doc_resource

Инструменты, требующие доступа на запись:

• create_project, delete_project
• create_branch, delete_branch, reset_from_parent
• provision_neon_auth, configure_neon_auth, provision_neon_data_api
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Транспорт Server-Sent Events (SSE) (устаревший)

MCP поддерживает два удалённых транспорта сервера: устаревший Server-Sent Events (SSE) и более новый, рекомендуемый Streamable HTTP. Если ваш LLM-клиент ещё не поддерживает Streamable HTTP, вы можете переключить конечную точку с https://mcp.neon.tech/mcp на https://mcp.neon.tech/sse, чтобы использовать SSE.

Выполните следующую команду, чтобы добавить Neon MCP Server для всех обнаруженных агентов и редакторов в вашем рабочем пространстве с использованием транспорта SSE:

npx add-mcp https://mcp.neon.tech/sse --type sse

Архитектура удалённого сервера

Удалённый сервер работает как приложение Next.js App Router на Vercel по адресу mcp.neon.tech.

[!NOTE] Корневой путь / перенаправляет на документацию Neon MCP Server. Посадочной страницы нет.

Основные области реализации:

• app/api/[transport]/route.ts: конечная точка транспорта MCP для Streamable HTTP (/mcp) и SSE (/sse)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: конечные точки потока OAuth
• app/.well-known/: конечные точки метаданных обнаружения OAuth
• mcp/: MCP-сервер, инструменты, обработчики, аналитика и интеграция Sentry
• lib/: вспомогательные функции, совместимые с Next.js (OAuth, конфигурация, обработка ошибок)
• mcp/utils/read-only.ts: режим только для чтения и обработка областей

Руководства

• Руководство по Neon MCP Server
• Подключение MCP-клиентов к Neon
• Cursor с Neon MCP Server
• Claude Code с Neon MCP Server
• Claude Desktop с Neon MCP Server
• Cline с Neon MCP Server
• Windsurf с Neon MCP Server
• Zed с Neon MCP Server

Возможности

Поддерживаемые инструменты

Neon MCP Server предоставляет следующие действия, которые представлены как «инструменты» для MCP-клиентов. Вы можете использовать эти инструменты для взаимодействия с вашими проектами и базами данных Neon с помощью команд на естественном языке.

Метаданные области действия инструментов

Каждое определение инструмента включает категорию scope, используемую для фильтрации инструментов на основе предоставленных прав и UX согласия. Текущие категории:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• null (инструменты без категории области)

Примечания:

• compare_database_schema относится к категории schema.
• provision_neon_data_api относится к категории data_api (отдельно от neon_auth).
• Принудительное применение режима только для чтения по-прежнему зависит от readOnlySafe и серверной логики режима только для чтения; scope — это метаданные категории, а не отдельный переключатель чтения/записи.
• В режиме ограничения проектом (?projectId=...) инструменты search и fetch недоступны.

Управление проектами:

• list_projects: Выводит список первых 10 проектов Neon в вашей учетной записи с краткой сводкой по каждому проекту. Если вы не можете найти нужный проект, увеличьте лимит, передав большее значение параметру limit.
• list_shared_projects: Выводит список проектов Neon, доступных текущему пользователю. Поддерживает параметр поиска и ограничение количества возвращаемых проектов (по умолчанию: 10).
• describe_project: Получает подробную информацию о конкретном проекте Neon, включая его ID, имя, а также связанные ветки и базы данных.
• create_project: Создает новый проект Neon в вашей учетной записи Neon. Проект выступает контейнером для веток, баз данных, ролей и вычислительных ресурсов.
• delete_project: Удаляет существующий проект Neon и все связанные с ним ресурсы.
• list_organizations: Выводит список всех организаций, к которым имеет доступ текущий пользователь. При желании можно отфильтровать по имени или ID организации с помощью параметра поиска.

Управление ветками:

• create_branch: Создает новую ветку в указанном проекте Neon. Использует функцию ветвления Neon для разработки, тестирования или миграций.
• delete_branch: Удаляет существующую ветку из проекта Neon.
• describe_branch: Получает сведения о конкретной ветке, такие как имя, ID и родительская ветка.
• list_branch_computes: Выводит список вычислительных конечных точек для проекта или конкретной ветки, включая ID вычислительного ресурса, тип, размер, время последней активности и информацию об автоматическом масштабировании.
• compare_database_schema: Показывает различия схемы между дочерней веткой и ее родительской.
• reset_from_parent: Сбрасывает текущую ветку к состоянию родительской, отбрасывая локальные изменения. Автоматически сохраняет резервную копию, если у ветки есть дочерние ветки, или по запросу сохраняет копию с пользовательским именем.

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

• get_connection_string: Возвращает строку подключения к вашей базе данных.
• run_sql: Выполняет один SQL-запрос к указанной базе данных Neon. Поддерживает операции чтения и записи.
• run_sql_transaction: Выполняет серию SQL-запросов в рамках одной транзакции к базе данных Neon.
• get_database_tables: Выводит список всех таблиц в указанной базе данных Neon.
• describe_table_schema: Получает определение схемы конкретной таблицы с описанием столбцов, типов данных и ограничений.

Миграции базы данных (изменения схемы):

• prepare_database_migration: Запускает процесс миграции базы данных. Важно: создает временную ветку для безопасного применения и тестирования миграции перед воздействием на основную ветку.
• complete_database_migration: Завершает и применяет подготовленную миграцию базы данных к основной ветке. Это действие объединяет изменения из временной ветки миграции и удаляет временные ресурсы.

Выполнение SQL-запросов и оптимизация:

• inspect_database: Запускает одну из 14 предопределенных диагностик Postgres только для чтения для ветки — размеры отношений и индексов, использование индексов и последовательного сканирования, активные запросы и блокировки, самые тяжелые и частые запросы, коэффициент попадания в кэш и размер рабочего набора, оценки autovacuum и раздувания, а также состояние репликации. Те же проверки, что и команда CLI neon inspect db. Четыре из них требуют расширения pg_stat_statements или neon.
• list_slow_queries: Выявляет узкие места производительности, находя самые медленные запросы в базе данных. Требует расширения pg_stat_statements.
• explain_sql_statement: Предоставляет подробные планы выполнения SQL-запросов для выявления узких мест производительности.
• prepare_query_tuning: Анализирует производительность запросов и предлагает оптимизации, например создание индексов. Создает временную ветку для безопасного тестирования этих оптимизаций.
• complete_query_tuning: Завершает настройку запросов, применяя оптимизации к основной ветке или отбрасывая их. Удаляет временную ветку настройки.

Neon Auth:

• provision_neon_auth: Подготавливает Neon Auth для проекта Neon. Позволяет разработчикам легко настроить инфраструктуру аутентификации, создав интеграцию с провайдером аутентификации.
• configure_neon_auth: Настраивает существующую интеграцию Neon Auth для ветки — управление доверенными источниками, доступом с localhost, методами аутентификации, OAuth-провайдерами и провайдером транзакционных писем.
• get_neon_auth_config: Считывает полную конфигурацию Neon Auth для ветки, включая метаданные интеграции и настраиваемые параметры (секреты скрыты).

Neon Data API:

• provision_neon_data_api: Подготавливает Neon Data API для доступа к базе данных через HTTP с опциональной JWT-аутентификацией через Neon Auth или внешние JWKS-провайдеры.

Поиск и обнаружение:

• search: Выполняет поиск по организациям, проектам и веткам, соответствующим запросу. Возвращает ID, заголовки и прямые ссылки на консоль Neon.
• fetch: Получает подробную информацию о конкретной организации, проекте или ветке по ID (обычно из инструмента поиска).

Наблюдаемость: эти инструменты требуют бета-версии платформы Neon и в настоящее время доступны только для проектов в регионе aws-us-east-2. Ветка без доступа к журналам возвращает HTTP 404 с причиной telemetry_not_enabled.

• query_logs: Запрашивает журналы OpenTelemetry, создаваемые бессерверными функциями Neon и другими сервисами. Используйте структурированные фильтры по источнику, имени службы, уровню серьезности и временному окну или необработанный logql для селекторов потоков и фильтров строк, которые невозможно выразить структурированными входными данными.
• list_log_fields: Выводит список полей журнала, для которых можно перечислить значения в ветке, например service_name, severity_text и scope_name. Используйте перед list_log_field_values.
• list_log_field_values: Выводит список уникальных значений поля журнала в пределах ветки и временного окна, чтобы найти конкретные значения для структурированных фильтров или необработанного logql.

Документация и ресурсы:

• list_docs_resources: Выводит список всех доступных страниц документации Neon, получая индекс из https://neon.com/docs/llms.txt. Возвращает URL-адреса и заголовки страниц, которые можно получить по отдельности с помощью инструмента get_doc_resource.
• get_doc_resource: Получает конкретную страницу документации Neon в виде содержимого Markdown. Сначала используйте инструмент list_docs_resources, чтобы найти доступные слаги страниц, затем передайте слаг этому инструменту.

Миграции

Миграции — это способ управления изменениями схемы базы данных с течением времени. С помощью MCP-сервера Neon LLM могут безопасно выполнять миграции с помощью отдельных команд «Start» (prepare_database_migration) и «Commit» (complete_database_migration).

Команда «Start» принимает миграцию и выполняет ее в новой временной ветке. По завершении эта команда подсказывает LLM, что следует протестировать миграцию в этой ветке. Затем LLM может выполнить команду «Commit», чтобы применить миграцию к исходной ветке.

Разработка

В этом проекте используется pnpm в качестве менеджера пакетов, закрепленный через Corepack.

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

Код MCP-сервера находится в корне репозитория — это приложение Next.js, развернутое на Vercel по адресу mcp.neon.tech.

corepack enable
pnpm install

Локальная разработка

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

Линтинг и проверка типов

pnpm lint
pnpm typecheck

Переменные окружения

Требуются для работы удаленного сервера:

Переменная	Описание
SERVER_HOST	URL сервера (по умолчанию VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL OAuth-провайдера Neon
CLIENT_ID	ID OAuth-клиента
CLIENT_SECRET	Секрет OAuth-клиента
COOKIE_SECRET	Секрет для подписанных cookie
KV_URL	URL Vercel KV (Upstash Redis)
OAUTH_DATABASE_URL	URL Postgres для хранения токенов

Необязательные:

Переменная	Описание
LOG_LEVEL	Уровень журналирования Winston: error, warn, info (по умолчанию), debug, verbose, silly

Пирамида тестирования

Все тесты запускаются из корня репозитория.

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

Стратегия тестирования:

• Отдавайте предпочтение E2E-тестам для транспорта/протокола и видимого пользователю поведения.
• Используйте интеграционные тесты для детерминированных контрактов инструментов и поведения рабочих процессов.
• Используйте модульные тесты для чистой логики и граничных случаев.
• Избегайте зависимости от доступности сторонних сервисов в тестах, блокирующих слияние; имитируйте внешние зависимости на уровнях интеграционных и модульных тестов.

Развертывание

Vercel автоматически развертывает удаленный сервер из конфигурации ветки репозитория. Среды предварительного просмотра доступны для pull request.