NeoSQL MCP 서버(neosql-mcp)를 외부 AI 클라이언트에 설치하면, Claude Code 같은 클라이언트가 데스크톱 앱에 있는 프로젝트의 커넥션으로 스키마를 읽고 ERD 를 설계하고 SQL 을 실행합니다. MCP 서버는 클라이언트가 실행하는 작은 프로그램으로, 받은 요청을 같은 기기의 데스크톱 앱에 넘깁니다. DB 접속 정보는 데스크톱 앱에만 있고 클라이언트 설정에는 들어가지 않습니다. MCP 가 무엇이고 외부 AI 에 어떤 안전장치가 걸리는지는 AI 와 MCP 에서 설명합니다.
준비할 것
- 데스크톱 앱: 같은 기기(macOS 또는 Windows)에 데스크톱 앱이 설치되어 있어야 합니다(설치와 업데이트). 웹 앱에서는 MCP 를 사용할 수 없습니다.
- Node.js 20 이상: 클라이언트가
npx로 MCP 서버를 다운로드해 실행합니다. 클라이언트가 실행되는 환경에서npx를 찾을 수 있어야 합니다. NeoSQLEnterprise 는 앱에 포함된 MCP 서버를 실행하므로 Node.js 가 필요 없습니다. 아래 NeoSQLEnterprise 에서 연결하기를 보세요. - 외부 AI 가 사용할 커넥션: 프로젝트의 AI 설정 창에서 커넥션의 사용 항목을 활성화합니다(프로젝트 AI 설정). 항목이 비활성화된 커넥션은 외부 AI 에게 보이지 않습니다.
- 로그인하지 않았으면 로컬 프로젝트만 다룹니다. 계정 프로젝트를 다루려면 데스크톱 앱에 로그인하세요.
설치 방법 선택하기
| 방법 | 사용할 수 있는 클라이언트 | 이럴 때 선택합니다 |
|---|---|---|
| 앱의 MCP 클라이언트 설정 창 | Claude Code, Codex, Gemini CLI, Cursor, VS Code | 대부분의 경우입니다. 클라이언트의 설정 파일에 바로 등록하거나, 작업 폴더에 대상 프로젝트를 고정한 설정 파일을 둡니다 |
| Claude 플러그인 | Claude Code, Claude 데스크톱 앱의 Cowork | Claude 의 플러그인으로 설치하고 업데이트하고 싶을 때 |
| 직접 설정 | stdio 방식의 MCP 서버를 실행할 수 있는 클라이언트 | 목록에 없는 클라이언트를 사용하거나 설정 파일을 직접 관리할 때 |
앱에서 등록하기
- 데스크톱 앱에서 프로젝트를 열고, 프로젝트 화면 위쪽의 AI 설정 버튼을 클릭합니다.
- 외부 AI 가 사용할 커넥션의 사용 항목을 활성화하고, 대상을 적지 않은 요청이 사용할 커넥션의 기본 항목을 선택한 뒤 저장 버튼을 클릭합니다.
- 창이 닫히면 AI 설정 버튼을 다시 클릭하고, 표 아래의 MCP 클라이언트 설정 버튼을 클릭합니다.
- 설정 범위 칸에서 전역 항목을 선택하고, 사용하는 클라이언트를 선택한 뒤 전역 등록 버튼을 클릭합니다.
- 확인 창에서 수정할 파일의 경로와 넣을 내용을 확인하고 창 아래쪽의 버튼을 클릭합니다. 버튼의 이름은 설정 파일과 NeoSQL 항목이 이미 있는지에 따라 다릅니다.
- 설정 파일에는 NeoSQL 항목만 더해지고 다른 설정은 그대로 보존됩니다.
- 한 작업 폴더에서만 사용하거나 대상 프로젝트를 고정하는 방법과, 클라이언트마다 설정 파일이 놓이는 자리는 MCP 클라이언트 설정 에서 설명합니다.
Claude 플러그인으로 설치하기
Claude Code 와 Claude 데스크톱 앱의 Cowork 에서는 NeoSQL MCP 를 플러그인으로 설치할 수 있습니다. 플러그인은 버전을 정해 둔 neosql-mcp 를 실행하고, 새 버전은 플러그인을 업데이트해 받습니다. Claude 의 채팅(Chat)에서는 플러그인의 MCP 서버가 실행되지 않습니다.
Claude 앱에서 추가하기
- claude.ai 나 Claude 데스크톱 앱에서 Customize › Plugins 를 엽니다.
NeoSQL MCP를 찾아 추가(Add) 버튼을 클릭합니다.- 플러그인에 로컬 MCP 서버가 들어 있다는 확인 창이 표시되면 계속(Continue) 버튼을 클릭합니다.
- Claude Code 에서 사용하려면 Claude Code 를 다시 시작합니다.
- 플러그인은 claude.ai 계정에 저장됩니다. 같은 계정으로 로그인한 Claude Code(2.1.273 이상)가 다음에 시작할 때 플러그인을 불러옵니다.
터미널에서 설치하기
claude.ai 계정으로 로그인하지 않고 Claude Code 를 사용하거나 명령으로 설치하려면, NeoSQL 이 제공하는 플러그인 marketplace 를 추가하고 플러그인을 설치합니다.
claude plugin marketplace add unvus/neosql-mcp
claude plugin install neosql-mcp@neosql
- 터미널에서 설치한 플러그인은 기본으로는 자동으로 업데이트되지 않습니다.
claude plugin update neosql-mcp@neosql명령으로 업데이트하거나, Claude Code 의/plugin화면의 Marketplaces 탭에서neosqlmarketplace 의 자동 업데이트를 활성화하세요.
플러그인과 다른 설정을 함께 사용할 때
- Claude Code 에 앱에서 등록하거나 직접 넣은 설정과 플러그인이 함께 있으면 MCP 서버가 둘 다 실행되어 NeoSQL 도구가 두 벌 보입니다. Claude Code 의
/mcp에서 실행 중인 서버를 확인하고 하나를 종료하세요. - 플러그인에는 대상 프로젝트를 고정하는 설정이 없습니다. 프로젝트를 고정하려면 고정할 작업 폴더에 앱의 작업 디렉토리 범위로 만든 설정 파일을 두고, 같은 폴더의
.claude/settings.local.json에 아래 항목을 더해 플러그인을 비활성화합니다. Claude 앱에서 추가한 플러그인은neosql-mcp@synced, 터미널에서 설치한 플러그인은neosql-mcp@neosql로 적습니다. 두 방법으로 모두 설치했으면 두 항목을 모두 적습니다.
{
"enabledPlugins": {
"neosql-mcp@synced": false
}
}
직접 설정하기
클라이언트의 설정 파일에 아래 내용을 넣습니다. 앱의 MCP 클라이언트 설정 창이 만드는 내용과 같습니다. 설정 파일이 놓이는 자리는 MCP 클라이언트 설정 에서 설명합니다.
Claude Code, Gemini CLI, Cursor:
{
"mcpServers": {
"neosql": {
"command": "npx",
"args": ["-y", "neosql-mcp"]
}
}
}
VS Code:
{
"servers": {
"neosql": {
"type": "stdio",
"command": "npx",
"args": ["-y", "neosql-mcp"]
}
}
}
Codex:
[mcp_servers.neosql]
command = "npx"
args = ["-y", "neosql-mcp"]
- 설정 파일에 이미 다른 MCP 서버가 있으면
neosql항목만 더합니다. - 목록에 없는 클라이언트도 stdio 방식의 MCP 서버를 실행할 수 있으면 같은 명령(
npx)과 인자(-y neosql-mcp)로 등록합니다. - 대상 프로젝트를 고정하려면 인자 끝에
--project-id=<프로젝트 ID>를 더합니다. 프로젝트 ID 는 앱의 MCP 클라이언트 설정 창에서 작업 디렉토리 범위를 선택하면 미리보기에 보입니다. 프로젝트를 고정하면 외부 AI 가 다른 프로젝트를 대상으로 할 수 없고, 새 프로젝트를 만드는 도구(create-project)도 거절됩니다.
NeoSQLEnterprise 에서 연결하기
NeoSQLEnterprise 는 회사가 설치해 운영하는 NeoSQL 서버에 연결하는 데스크톱 앱입니다. NeoSQLEnterprise 에서도 같은 방법으로 MCP 서버를 등록합니다. 다른 점은 아래와 같습니다.
- NeoSQLEnterprise 에는 MCP 서버가 들어 있습니다. 앱의 MCP 클라이언트 설정 창이 만드는 설정은
npx대신 NeoSQLEnterprise 앱의 실행 파일로 이 MCP 서버를 실행합니다. 그래서 Node.js 와 인터넷 연결이 없어도 되고, MCP 서버의 버전이 늘 앱과 같습니다. - 설정에는 앱 실행 파일의 경로, 앱 안의 MCP 서버 파일 경로,
ELECTRON_RUN_AS_NODE환경 변수,--profile=enterprise인자가 들어갑니다.ELECTRON_RUN_AS_NODE가 있어야 앱 실행 파일이 앱 화면을 띄우지 않고 MCP 서버만 실행합니다.--profile=enterprise가 있어야 MCP 서버가 NeoSQL 앱 대신 NeoSQLEnterprise 앱에 요청을 넘깁니다. - 직접 설정할 때는 앱의 설정 창에서 미리보기를 복사해 붙여 넣으세요. macOS 의 응용 프로그램 폴더에 설치한 경우 아래와 같습니다.
{
"mcpServers": {
"neosql": {
"command": "/Applications/NeoSQLEnterprise.app/Contents/MacOS/NeoSQLEnterprise",
"args": [
"/Applications/NeoSQLEnterprise.app/Contents/Resources/neosql-mcp/neosql-mcp.cjs",
"--profile=enterprise"
],
"env": { "ELECTRON_RUN_AS_NODE": "1" }
}
}
}
- 앱을 다른 폴더로 옮기거나 다른 폴더에 다시 설치하면 설정에 적힌 경로가 맞지 않아 MCP 서버가 시작되지 않습니다. 앱에서 다시 등록하세요. 앱을 업데이트할 때는 경로가 바뀌지 않습니다.
- Claude 플러그인은 NeoSQL 앱에만 연결하고 NeoSQLEnterprise 앱에는 연결하지 않습니다. Claude Code 에서는 앱에서 등록하거나 직접 설정하세요.
- 두 앱은 설정 파일의 같은
neosql항목을 사용하므로, 한 클라이언트는 두 앱 가운데 하나에만 연결됩니다. 한 앱에서 등록하면 다른 앱이 만든 항목이 바뀝니다.
연결 확인하기
- 데스크톱 앱을 실행해 둡니다. 종료되어 있으면 외부 AI 가 도구를 호출할 때 MCP 서버가 앱을 띄우고 최대 40초 동안 준비를 기다립니다.
- 외부 AI 클라이언트를 다시 시작하고, 클라이언트의 MCP 서버 목록에
neosql이 연결되어 있는지 확인합니다(Claude Code 는/mcp. 플러그인은plugin:neosql-mcp:neosql로 보입니다). - 대화창에서 "NeoSQL 프로젝트 목록을 보여 줘" 처럼 요청합니다. 외부 AI 가
list-projects도구로 프로젝트 목록을 받으면 데스크톱 앱까지 연결된 것입니다.
- 연결되지 않으면 문제 해결 의 'MCP 가 연결되지 않을 때' 를 확인하세요.
- 연결한 뒤 외부 AI 가 할 수 있는 일은 MCP 도구 에서 설명합니다. 처음부터 끝까지 따라 해 보려면 외부 AI 로 ERD 설계하기(MCP) 를 읽으세요.
관련 페이지
- AI 와 MCP: MCP 의 개념과 외부 AI 에 걸리는 안전장치입니다.
- MCP 클라이언트 설정: 앱의 설정 창, 설정 범위, 클라이언트별 설정 파일의 자리입니다.
- 프로젝트 AI 설정: 커넥션마다 MCP 사용과 변경 정책을 정하는 창입니다.
- MCP 도구: 외부 AI 가 호출할 수 있는 도구와 받는 값입니다.
- 문제 해결: MCP 가 연결되지 않을 때 확인할 것입니다.