네온 MCP 서버

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

모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하도록 설계된 새로운 표준화된 프로토콜 입니다. 이 저장소는 Neon 용 설치 프로그램과 MCP 서버를 제공합니다.

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

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

자연어 상호작용: 직관적인 대화형 명령을 사용하여 Neon 데이터베이스를 관리합니다.
간소화된 데이터베이스 관리: SQL을 작성하거나 Neon API를 직접 사용하지 않고도 복잡한 작업을 수행할 수 있습니다.
비개발자를 위한 접근성: 다양한 기술적 배경을 가진 사용자가 Neon 데이터베이스와 상호 작용할 수 있도록 지원합니다.
데이터베이스 마이그레이션 지원: 자연어를 통해 시작된 데이터베이스 스키마 변경에 대해 Neon의 분기 기능을 활용합니다.

예를 들어, Claude Desktop이나 모든 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?

[!메모]
Neon MCP 서버는 자연어 요청을 통해 강력한 데이터베이스 관리 기능을 제공합니다. LLM에서 요청한 작업을 실행하기 전에 항상 검토하고 권한을 부여하십시오 . 권한이 있는 사용자와 애플리케이션만 Neon MCP 서버와 Neon API 키에 액세스할 수 있도록 하십시오.

Neon MCP 서버 설정

MCP 클라이언트를 Neon에 연결하는 데는 두 가지 옵션이 있습니다.

원격 MCP 서버(미리보기): OAuth 인증을 사용하여 Neon의 관리형 MCP 서버에 연결합니다. 이 방법은 API 키를 관리할 필요가 없어 더욱 편리합니다. 또한, 최신 기능 및 개선 사항이 출시되는 즉시 자동으로 제공됩니다.
로컬 MCP 서버: Neon API 키로 인증하여 로컬 컴퓨터에서 Neon MCP 서버를 실행합니다.

필수 조건

MCP 클라이언트 애플리케이션.
네온 계정 .
Node.js (>= v18.0.0) 및 npm: nodejs.org 에서 다운로드하세요.

로컬 MCP 서버 설정에는 Neon API 키도 필요합니다. Neon API 키 생성 방법은 Neon API 키 설명서를 참조하세요.

옵션 1. 원격 호스팅 MCP 서버(미리 보기)

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

클라이언트의 MCP 서버 구성 파일(예: mcp.json , mcp_config.json )에 다음 "Neon" 항목을 추가합니다.지엑스피1
구성 파일을 저장합니다.
MCP 클라이언트를 다시 시작하거나 새로 고칩니다.
브라우저에 OAuth 창이 열립니다. 안내에 따라 MCP 클라이언트가 Neon 계정에 액세스할 수 있도록 권한을 부여하세요.

옵션 2. 로컬 MCP 서버

로컬 컴퓨터에서 Neon MCP 서버를 실행합니다.

Smithery를 통한 설정:

npx -y @smithery/cli@latest install neon --client <client_name>

Neon API 키를 입력하라는 메시지가 표시됩니다. 필수 구성 요소 섹션에서 받은 API 키를 입력하세요. <client_name> MCP 클라이언트 애플리케이션 이름으로 바꾸세요. 지원되는 클라이언트 이름은 다음과 같습니다.

Claude 데스크탑 용 claude
Cursor 용 cursor ( smithery 통해 설치하면 MCP 서버가 Cursor의 글로벌 MCP 서버가 됨)
Windsurf Editor를 위한 windsurf
Roo Cline VS Code 확장을 위한 roo-cline
위티 를 위한 witsy
enconvo 를 위한 enconvo
Visual Studio Code 용 vscode (미리 보기)

설치 후 MCP 클라이언트를 다시 시작하세요.

npm을 통한 설정

여기에 귀하의 MCP 클라이언트가 나열되어 있지 않으면 Neon MCP 서버 세부 정보를 클라이언트의 mcp_config 파일에 수동으로 추가할 수 있습니다.

클라이언트의 mcp_config 파일에 있는 mcpServers 섹션에 다음 JSON 구성을 추가하고 <YOUR_NEON_API_KEY> 실제 Neon API 키로 바꿉니다.

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon",
        "start",
        "<YOUR_NEON_API_KEY>"
      ]
    }
  }
}

문제 해결

클라이언트가 MCP 서버 구성에 JSON 사용하지 않는 경우(예: 이전 버전의 Cursor), 메시지가 표시되면 다음 명령을 사용할 수 있습니다.

npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>

Windows에서 문제 해결

Windows를 사용 중이고 MCP 서버를 추가하는 동안 문제가 발생하는 경우, 명령 프롬프트( cmd ) 또는 Linux용 Windows 하위 시스템( wsl )을 사용하여 필요한 명령을 실행해야 할 수 있습니다. 구성 설정은 다음과 유사할 수 있습니다.

{
  "mcpServers": {
    "neon": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@neondatabase/mcp-server-neon",
        "start",
        "<YOUR_NEON_API_KEY>"
      ]
    }
  }
}

{
  "mcpServers": {
    "neon": {
      "command": "wsl",
      "args": [
        "npx",
        "-y",
        "@neondatabase/mcp-server-neon",
        "start",
        "<YOUR_NEON_API_KEY>"
      ]
    }
  }
}

가이드

특징

지원되는 도구

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

프로젝트 관리:

list_projects : Neon 프로젝트 목록을 검색하여 Neon 계정과 관련된 각 프로젝트에 대한 요약을 제공합니다.
describe_project : ID, 이름, 관련 브랜치 및 데이터베이스를 포함하여 특정 Neon 프로젝트에 대한 자세한 정보를 가져옵니다.
create_project : Neon 계정에 새 Neon 프로젝트를 생성합니다. 프로젝트는 브랜치, 데이터베이스, 역할 및 컴퓨팅을 위한 컨테이너 역할을 합니다.
delete_project : 기존 Neon 프로젝트와 관련 리소스를 모두 삭제합니다.

지점 관리:

create_branch : 지정된 Neon 프로젝트 내에 새 브랜치를 생성합니다. 개발, 테스트 또는 마이그레이션에 Neon의 브랜치 기능을 활용합니다.
delete_branch : Neon 프로젝트에서 기존 브랜치를 삭제합니다.
describe_branch : 이름, ID, 상위 브랜치 등 특정 브랜치에 대한 세부 정보를 검색합니다.

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 : 준비된 데이터베이스 마이그레이션을 완료하고 메인 브랜치에 적용합니다. 이 작업은 임시 마이그레이션 브랜치의 변경 사항을 병합하고 임시 리소스를 정리합니다.

네온 인증:

provision_neon_auth : Neon 프로젝트에 Neon Auth를 프로비저닝하는 작업입니다. 개발자는 Stack Auth( @stackframe/stack )와 통합하여 인증 인프라를 쉽게 설정할 수 있습니다.

이주

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

"Start" 명령은 마이그레이션을 수락하고 새 임시 브랜치에서 실행합니다. 이 명령은 LLM에 해당 브랜치에서 마이그레이션을 테스트해야 한다는 힌트를 제공합니다. LLM은 "Commit" 명령을 실행하여 마이그레이션을 원래 브랜치에 적용할 수 있습니다.

개발

MCP CLI 클라이언트를 사용한 개발

MCP 서버에서 반복 작업을 수행하는 가장 쉬운 방법은 mcp-client/ 사용하는 것입니다. 자세한 내용은 mcp-client/README.md 참조하세요.

npm install
npm run build
npm run watch # You can keep this open.
cd mcp-client/ && NEON_API_KEY=... npm run start:mcp-server-neon

Claude Desktop(로컬 MCP 서버)을 사용한 개발

npm install
npm run build
npm run watch # You can keep this open.
node dist/index.js init $NEON_API_KEY

그런 다음 변경 사항을 테스트할 때마다 Claude를 다시 시작합니다 .

테스트

테스트를 실행하려면 .env.example 파일에 따라 .env 파일을 설정해야 합니다.

npm run test