Neon MCP Server

공식

Neon 서버리스 Postgres 플랫폼과 상호작용합니다.

GitHub

611

문서

Neon MCP 서버

Neon MCP 서버는 자연어로 Neon Postgres 데이터베이스와 상호 작용할 수 있게 해주는 오픈 소스 도구입니다.

모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위해 설계된 표준화된 프로토콜입니다. 이 저장소는 Neon을 위한 원격 MCP 서버를 제공합니다.

Neon의 MCP 서버는 자연어 요청과 Neon API 사이의 가교 역할을 합니다. MCP를 기반으로 구축되어, 여러분의 요청을 필요한 API 호출로 변환하여 프로젝트 및 브랜치 생성, 쿼리 실행, 데이터베이스 마이그레이션 수행과 같은 작업을 원활하게 관리할 수 있도록 해줍니다.

Neon MCP 서버의 주요 기능은 다음과 같습니다:

자연어 상호 작용: 직관적이고 대화형 명령을 사용하여 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 서버 보안 고려 사항
Neon MCP 서버는 자연어 요청을 통해 강력한 데이터베이스 관리 기능을 부여합니다. 실행 전에 항상 LLM이 요청한 작업을 검토하고 승인하십시오. 승인된 사용자와 애플리케이션만 Neon MCP 서버에 접근할 수 있도록 하십시오.

Neon MCP 서버는 로컬 개발 및 IDE 통합 전용입니다. 프로덕션 환경에서는 Neon MCP 서버를 사용하지 않는 것이 좋습니다. 이 서버는 우발적이거나 승인되지 않은 변경을 초래할 수 있는 강력한 작업을 실행할 수 있습니다.

자세한 내용은 MCP 보안 지침 →을 참조하십시오.

Neon MCP 서버 설정

Neon MCP 서버를 설정하는 몇 가지 옵션이 있습니다:

API 키를 사용한 빠른 설정 (Cursor, VS Code, Claude Code): neonctl@latest init를 실행하여 하나의 명령으로 Neon의 MCP 서버, 에이전트 스킬, VS Code 확장을 자동으로 구성합니다.
원격 MCP 서버 (OAuth 기반 인증): OAuth를 사용하여 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 API 키를 관리할 필요가 없으므로 더 편리합니다. 또한 최신 기능과 개선 사항이 출시되는 즉시 자동으로 받을 수 있습니다.
원격 MCP 서버 (API 키 기반 인증): API 키를 사용하여 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 OAuth를 사용할 수 없는 환경에서 원격 에이전트를 Neon에 연결하려는 경우에 유용합니다. 또한 최신 기능과 개선 사항이 출시되는 즉시 자동으로 받을 수 있습니다.

사전 요구 사항

MCP 클라이언트 애플리케이션.
Neon 계정.
Node.js (>= v18.0.0): nodejs.org에서 다운로드하십시오.

개발의 경우 Node.js 22+가 필요합니다 (pnpm은 Corepack을 통해 제공됩니다 — corepack enable을 실행하여 활성화하십시오).

옵션 1. API 키를 사용한 빠른 설정

API 키를 수동으로 생성하고 싶지 않으신가요?

neonctl@latest init을 실행하여 하나의 명령으로 Neon의 MCP 서버를 자동으로 구성하십시오:

npx neonctl@latest init

이것은 Cursor, VS Code (GitHub Copilot), Claude Code와 함께 작동합니다. OAuth를 통해 인증하고, Neon API 키를 생성하며, 편집기를 자동으로 구성합니다.

옵션 2. 원격 호스팅 MCP 서버 (OAuth 기반 인증)

OAuth를 사용하여 Neon의 관리형 MCP 서버에 연결합니다. 이것은 가장 쉬운 설정이며, 이 서버의 로컬 설치가 필요 없고 클라이언트에 Neon API 키를 구성할 필요가 없습니다.

작업 공간에서 감지된 모든 에이전트 및 편집기에 대해 Neon MCP 서버를 추가하려면 다음 명령을 실행하십시오:

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

프로젝트 범위 대신 전역 MCP 서버 목록에 Neon MCP 서버를 추가하려면 -g 플래그를 추가하십시오.

또는 클라이언트의 MCP 서버 구성 파일(예: mcp.json, mcp_config.json)에 다음 "Neon" 항목을 추가할 수 있습니다:

{
  "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 계정의 프로젝트에서 작동합니다. 조직에 속한 프로젝트에 접근하거나 관리하려면 MCP 클라이언트 프롬프트에 org_id 또는 project_id를 명시적으로 제공해야 합니다.

옵션 3. 원격 호스팅 MCP 서버 (API 키 기반 인증)

원격 MCP 서버는 클라이언트가 지원하는 경우 Authorization 헤더의 API 키를 사용한 인증도 지원합니다.

Neon 콘솔에서 Neon API 키를 생성합니다. 그런 다음 작업 공간에서 감지된 모든 에이전트 및 편집기에 대해 Neon MCP 서버를 추가하려면 다음 명령을 실행하십시오:

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

또는 클라이언트의 MCP 서버 구성 파일(예: mcp.json, mcp_config.json)에 다음 "Neon" 항목을 추가할 수 있습니다:

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

조직의 API 키를 제공하면 해당 조직의 프로젝트로만 접근을 제한할 수 있습니다.

범위 및 읽기 전용 모드

Neon MCP는 OAuth 범위 read, write, *을 지원합니다 (*은 둘 다를 의미). MCP 클라이언트가 이러한 범위를 직접 요청하거나 OAuth 권한 UI에서 선택할 수 있습니다.

읽기 전용 모드는 사용 가능한 도구를 제한하여 프로젝트 생성, 브랜치 생성, 마이그레이션 실행과 같은 쓰기 작업을 비활성화합니다. 읽기 전용 도구에는 프로젝트 나열, 스키마 설명, 데이터 쿼리, 성능 지표 보기가 포함됩니다.

읽기 전용 모드는 두 가지 방법으로 설정할 수 있습니다:

OAuth 범위 선택 (권장): OAuth에서 권한 UI의 전체 접근을 선택 해제하여 읽기 전용을 선택합니다.
readonly 쿼리 매개변수: MCP 서버 URL에 ?readonly=true을 추가합니다:

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

쿼리 매개변수 동작 방식:

API 키 흐름: readonly=true는 읽기 전용 모드를 활성화하는 방법입니다 (이 흐름에는 OAuth 범위 교환이 없습니다).
OAuth 흐름: readonly=true는 OAuth 범위를 재정의합니다. 이것이 없으면 읽기 전용 여부는 OAuth 동의 UI에서 선택한 범위에 따라 결정됩니다.

레거시 HTTP 헤더 x-read-only도 대체 수단으로 지원됩니다 (쿼리 매개변수보다 우선 순위가 낮음).

참고: 읽기 전용 모드는 사용 가능한 _도구_를 제한합니다. 또한 run_sql 도구는 읽기 전용 쿼리에만 사용할 수 있습니다.

접근 제어를 위한 URL 쿼리 매개변수

권한 부여 컨텍스트(범주 카테고리, 프로젝트 범위 지정, 읽기 전용 모드)는 MCP 서버 URL의 URL 쿼리 매개변수를 통해 구성됩니다. 구성은 모든 요청과 함께 전달되며 즉시 적용됩니다 — 재인증이 필요하지 않습니다.

매개변수	설명	예시
`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
get_connection_string
search, fetch, list_docs_resources, get_doc_resource

쓰기 접근이 필요한 도구:

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

서버 전송 이벤트(SSE) 전송 (지원 중단됨)

MCP는 두 가지 원격 서버 전송을 지원합니다: 지원 중단된 서버 전송 이벤트(SSE)와 더 새롭고 권장되는 스트리밍 가능 HTTP. LLM 클라이언트가 아직 스트리밍 가능 HTTP를 지원하지 않는 경우, 엔드포인트를 https://mcp.neon.tech/mcp에서 https://mcp.neon.tech/sse로 전환하여 SSE를 대신 사용할 수 있습니다.

SSE 전송을 사용하여 작업 공간에서 감지된 모든 에이전트 및 편집기에 대해 Neon MCP 서버를 추가하려면 다음 명령을 실행하십시오:

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

원격 서버 아키텍처

원격 서버는 Vercel의 mcp.neon.tech에서 Next.js 앱 라우터 애플리케이션으로 실행됩니다.

[!NOTE] 루트 / 경로는 Neon MCP 서버 문서로 리디렉션됩니다. 랜딩 페이지는 없습니다.

핵심 구현 영역:

landing/app/api/[transport]/route.ts: 스트리밍 가능 HTTP(/mcp) 및 SSE(/sse)를 위한 MCP 전송 엔드포인트
landing/app/api/authorize/, landing/app/callback/, landing/app/api/token/, landing/app/api/revoke/: OAuth 흐름 엔드포인트
landing/app/.well-known/: OAuth 검색 메타데이터 엔드포인트
landing/mcp-src/: MCP 서버, 도구, 핸들러, 분석 및 Sentry 통합
landing/lib/: Next.js 호환 헬퍼 (OAuth, 구성, 오류 처리)
landing/mcp-src/utils/read-only.ts: 읽기 전용 모드 및 범위 처리

가이드

기능

지원되는 도구

Neon MCP 서버는 MCP 클라이언트에 "도구"로 노출되는 다음 작업을 제공합니다. 이러한 도구를 사용하여 자연어 명령으로 Neon 프로젝트 및 데이터베이스와 상호 작용할 수 있습니다.

도구 범위 메타데이터

각 도구 정의에는 권한 부여 기반 도구 필터링 및 동의 UX에 사용되는 scope 카테고리가 포함됩니다. 현재 카테고리는 다음과 같습니다:

projects
branches
schema
querying
neon_auth
data_api
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: ID, 이름, 연결된 브랜치 및 데이터베이스를 포함하여 특정 Neon 프로젝트에 대한 자세한 정보를 가져옵니다.
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: 지정된 Neon 데이터베이스에 대해 단일 SQL 쿼리를 실행합니다. 읽기 및 쓰기 작업을 모두 지원합니다.
run_sql_transaction: Neon 데이터베이스에 대해 단일 트랜잭션 내에서 일련의 SQL 쿼리를 실행합니다.
get_database_tables: 지정된 Neon 데이터베이스 내의 모든 테이블을 나열합니다.
describe_table_schema: 열, 데이터 유형 및 제약 조건을 자세히 설명하는 특정 테이블의 스키마 정의를 검색합니다.

데이터베이스 마이그레이션 (스키마 변경):

prepare_database_migration: 데이터베이스 마이그레이션 프로세스를 시작합니다. 중요한 점은, 메인 브랜치에 영향을 주기 전에 마이그레이션을 안전하게 적용하고 테스트하기 위해 임시 브랜치를 생성한다는 것입니다.
complete_database_migration: 준비된 데이터베이스 마이그레이션을 메인 브랜치에 완료하고 적용합니다. 이 작업은 임시 마이그레이션 브랜치의 변경 사항을 병합하고 임시 리소스를 정리합니다.

SQL 쿼리 및 최적화:

list_slow_queries: 데이터베이스에서 가장 느린 쿼리를 찾아 성능 병목 현상을 식별합니다. pg_stat_statements 확장이 필요합니다.
explain_sql_statement: 성능 병목 현상을 식별하는 데 도움이 되도록 SQL 쿼리에 대한 자세한 실행 계획을 제공합니다.
prepare_query_tuning: 쿼리 성능을 분석하고 인덱스 생성과 같은 최적화를 제안합니다. 이러한 최적화를 안전하게 테스트하기 위해 임시 브랜치를 생성합니다.
complete_query_tuning: 최적화를 메인 브랜치에 적용하거나 폐기하여 쿼리 튜닝을 완료합니다. 임시 튜닝 브랜치를 정리합니다.

Neon Auth:

provision_neon_auth: Neon 프로젝트에 Neon Auth를 프로비저닝합니다. 개발자가 인증 제공업체와의 통합을 생성하여 인증 인프라를 쉽게 설정할 수 있도록 합니다.

Neon Data API:

provision_neon_data_api: Neon Auth 또는 외부 JWKS 제공업체를 통한 선택적 JWT 인증과 함께 HTTP 기반 데이터베이스 접근을 위해 Neon Data API를 프로비저닝합니다.

검색 및 발견:

search: 쿼리와 일치하는 조직, 프로젝트 및 브랜치를 검색합니다. ID, 제목 및 Neon 콘솔로의 직접 링크를 반환합니다.
fetch: ID(일반적으로 검색 도구에서 가져옴)를 사용하여 특정 조직, 프로젝트 또는 브랜치에 대한 자세한 정보를 가져옵니다.

문서 및 리소스:

list_docs_resources: https://neon.com/docs/llms.txt에서 색인을 가져와 사용 가능한 모든 Neon 문서 페이지를 나열합니다. get_doc_resource 도구를 사용하여 개별적으로 가져올 수 있는 페이지 URL과 제목을 반환합니다.
get_doc_resource: 특정 Neon 문서 페이지를 마크다운 콘텐츠로 가져옵니다. 먼저 list_docs_resources 도구를 사용하여 사용 가능한 페이지 슬러그를 찾은 다음, 해당 슬러그를 이 도구에 전달하십시오.

마이그레이션

마이그레이션은 시간 경과에 따른 데이터베이스 스키마 변경 사항을 관리하는 방법입니다. Neon MCP 서버를 통해 LLM은 별도의 "시작" (prepare_database_migration) 및 "커밋" (complete_database_migration) 명령을 사용하여 안전하게 마이그레이션을 수행할 수 있습니다.

"시작" 명령은 마이그레이션을 수락하고 새 임시 브랜치에서 실행합니다. 반환 시 이 명령은 LLM에게 이 브랜치에서 마이그레이션을 테스트해야 한다고 힌트를 줍니다. 그런 다음 LLM은 "커밋" 명령을 실행하여 원래 브랜치에 마이그레이션을 적용할 수 있습니다.

개발

이 프로젝트는 Corepack을 통해 고정된 pnpm을 패키지 관리자로 사용합니다.

프로젝트 구조

MCP 서버 코드는 landing/ 디렉터리에 있으며, 이는 mcp.neon.tech의 Vercel에 배포된 Next.js 애플리케이션입니다.

cd landing
corepack enable
pnpm install

로컬 개발

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

린팅 및 유형 검사

pnpm run lint
pnpm run typecheck

환경 변수

원격 서버 런타임에 필요:

변수	설명
`SERVER_HOST`	서버 URL (기본값: `VERCEL_URL`)
`UPSTREAM_OAUTH_HOST`	Neon OAuth 제공업체 URL
`CLIENT_ID`	OAuth 클라이언트 ID
`CLIENT_SECRET`	OAuth 클라이언트 시크릿
`COOKIE_SECRET`	서명된 쿠키를 위한 시크릿
`KV_URL`	Vercel KV (Upstash Redis) URL
`OAUTH_DATABASE_URL`	토큰 저장을 위한 Postgres URL

선택 사항:

변수	설명
`LOG_LEVEL`	Winston 로그 레벨: `error`, `warn`, `info` (기본값), `debug`, `verbose`, `silly`

테스트 피라미드

모든 테스트는 landing/에서 실행됩니다.

cd landing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

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

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

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

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

테스트 전략:

전송/프로토콜 및 사용자에게 보이는 동작에는 E2E를 선호합니다.
결정적인 도구 계약 및 워크플로 동작에는 통합 테스트를 사용합니다.
순수 로직 및 엣지 케이스에는 단위 테스트를 사용합니다.
병합 게이팅 테스트에서 타사 가동 시간에 의존하지 마십시오. 통합/단위 계층에서 외부 종속성을 모의 처리하십시오.

배포

Vercel은 리포지토리 브랜치 구성에서 원격 서버를 자동으로 배포합니다. 풀 리퀘스트에 대해 미리보기 환경을 사용할 수 있습니다.