시작하기

MCP 설치와 연결

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 데스크톱 앱의 CoworkClaude 의 플러그인으로 설치하고 업데이트하고 싶을 때
직접 설정stdio 방식의 MCP 서버를 실행할 수 있는 클라이언트목록에 없는 클라이언트를 사용하거나 설정 파일을 직접 관리할 때

앱에서 등록하기

  1. 데스크톱 앱에서 프로젝트를 열고, 프로젝트 화면 위쪽의 AI 설정 버튼을 클릭합니다.
  2. 외부 AI 가 사용할 커넥션의 사용 항목을 활성화하고, 대상을 적지 않은 요청이 사용할 커넥션의 기본 항목을 선택한 뒤 저장 버튼을 클릭합니다.
  3. 창이 닫히면 AI 설정 버튼을 다시 클릭하고, 표 아래의 MCP 클라이언트 설정 버튼을 클릭합니다.
  4. 설정 범위 칸에서 전역 항목을 선택하고, 사용하는 클라이언트를 선택한 뒤 전역 등록 버튼을 클릭합니다.
  5. 확인 창에서 수정할 파일의 경로와 넣을 내용을 확인하고 창 아래쪽의 버튼을 클릭합니다. 버튼의 이름은 설정 파일과 NeoSQL 항목이 이미 있는지에 따라 다릅니다.
  • 설정 파일에는 NeoSQL 항목만 더해지고 다른 설정은 그대로 보존됩니다.
  • 한 작업 폴더에서만 사용하거나 대상 프로젝트를 고정하는 방법과, 클라이언트마다 설정 파일이 놓이는 자리는 MCP 클라이언트 설정 에서 설명합니다.

Claude 플러그인으로 설치하기

Claude Code 와 Claude 데스크톱 앱의 Cowork 에서는 NeoSQL MCP 를 플러그인으로 설치할 수 있습니다. 플러그인은 버전을 정해 둔 neosql-mcp 를 실행하고, 새 버전은 플러그인을 업데이트해 받습니다. Claude 의 채팅(Chat)에서는 플러그인의 MCP 서버가 실행되지 않습니다.

Claude 앱에서 추가하기

  1. claude.ai 나 Claude 데스크톱 앱에서 Customize › Plugins 를 엽니다.
  2. NeoSQL MCP 를 찾아 추가(Add) 버튼을 클릭합니다.
  3. 플러그인에 로컬 MCP 서버가 들어 있다는 확인 창이 표시되면 계속(Continue) 버튼을 클릭합니다.
  4. 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 탭에서 neosql marketplace 의 자동 업데이트를 활성화하세요.

플러그인과 다른 설정을 함께 사용할 때

  • 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 항목을 사용하므로, 한 클라이언트는 두 앱 가운데 하나에만 연결됩니다. 한 앱에서 등록하면 다른 앱이 만든 항목이 바뀝니다.

연결 확인하기

  1. 데스크톱 앱을 실행해 둡니다. 종료되어 있으면 외부 AI 가 도구를 호출할 때 MCP 서버가 앱을 띄우고 최대 40초 동안 준비를 기다립니다.
  2. 외부 AI 클라이언트를 다시 시작하고, 클라이언트의 MCP 서버 목록에 neosql 이 연결되어 있는지 확인합니다(Claude Code 는 /mcp. 플러그인은 plugin:neosql-mcp:neosql 로 보입니다).
  3. 대화창에서 "NeoSQL 프로젝트 목록을 보여 줘" 처럼 요청합니다. 외부 AI 가 list-projects 도구로 프로젝트 목록을 받으면 데스크톱 앱까지 연결된 것입니다.

관련 페이지

  • AI 와 MCP: MCP 의 개념과 외부 AI 에 걸리는 안전장치입니다.
  • MCP 클라이언트 설정: 앱의 설정 창, 설정 범위, 클라이언트별 설정 파일의 자리입니다.
  • 프로젝트 AI 설정: 커넥션마다 MCP 사용과 변경 정책을 정하는 창입니다.
  • MCP 도구: 외부 AI 가 호출할 수 있는 도구와 받는 값입니다.
  • 문제 해결: MCP 가 연결되지 않을 때 확인할 것입니다.