Neo4j MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

임의의 Cypher 읽기 또는 쓰기 쿼리 실행
스키마 내재화: 레이블, 관계 유형, 속성 키, 제약 조건, 인덱스
Neo4j Community, Enterprise, AuraDB 및 Neo4j Desktop에서 작동합니다
Neo4j Aura에서 인스턴스 프로비저닝을 위한 별도의 Aura-admin 서버
작고 집중된 도구 표면 — 마법 없음; 모든 Cypher를 제어하세요

라이브 데모

실제 사용 모습

neo4j.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neo4j",
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "neo4j": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-neo4j-cypher"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add neo4j -- uvx mcp-neo4j-cypher

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Neo4j

5분 안에 낯선 그래프 스키마 탐색하기

👤 Neo4j DB를 상속받은 엔지니어 / 분석가 ⏱ ~15 min beginner

언제 쓸까: 문서 없이 그래프 DB가 전달되었습니다. 유용한 쿼리를 작성하기 전에 멘탈 모델이 필요합니다.

사전 조건

Neo4j Bolt URL + 사용자/암호 — NEO4J_URI=bolt://host:7687, NEO4J_USERNAME, NEO4J_PASSWORD
탐색을 위해 읽기 전용 사용자 권장 — CREATE USER claude SET PASSWORD '...' SET ROLES reader

흐름

스키마 개요 가져오기

get_neo4j_schema를 호출하세요. 노드 레이블, 관계 유형 및 가장 일반적인 (label)-[rel]->(label) 패턴을 요약하세요.✓ 복사됨

→ 샘플 트리플이 있는 스키마 요약
대표 노드 샘플링

3가지 가장 일반적인 레이블에 대해 각각 MATCH (n:Label) RETURN n LIMIT 3을 실행하세요. 각 레이블이 무엇을 나타내는지 설명하세요.✓ 복사됨

→ 레이블의 의미론적 설명
가능한 ER 모델 도출

스키마 + 샘플을 기반으로 이 그래프의 '엔티티' 스토리를 산문으로 설명하세요. 주 객체는 무엇이고, 무엇이 연결되어 있으며, 무엇이 주변인가요?✓ 복사됨

→ 명확한 도메인 모델 설명

결과: 원래 작성자와 검증할 수 있는 한 페이지 도메인 모델입니다.

함정

작은 그래프를 샘플링하면 오도하는 패턴이 생깁니다 — 또한 MATCH (n)-[r]->() RETURN type(r), count(*)를 통해 어떤 관계가 지배적인지 확인하세요

함께 쓰기: filesystem

그래프 쿼리를 작성하여 사기 네트워크 감지하기

👤 위험 / 사기 분석가 ⏱ ~40 min advanced

언제 쓸까: 계정 간 공유 기기 또는 공유 주소 사기 네트워크를 의심합니다.

사전 조건

User, Device, Address, Payment 노드 및 :USED, :LIVES_AT, :PAID 관계가 있는 그래프 — 일반적인 사기 그래프 구조

흐름

공유 기기 찾기

지난 30일 동안 3명 이상의 다른 사용자가 사용한 기기를 찾으세요. device_id + 사용자_id 목록 + 각 쌍별 마지막 사용 타임스탬프를 반환하세요.✓ 복사됨

→ 네트워크 후보
연결된 컴포넌트 크기로 점수 지정

GDS 또는 순수 Cypher를 사용하여 User-(:USED)-Device-(:USED)-User에 대한 연결된 컴포넌트를 계산하세요. 크기별 상위 10개 컴포넌트를 반환하세요.✓ 복사됨

→ 의심스러운 클러스터
실행 가능한 목록 생성

각 상위 클러스터에 대해 고유한 사용자, 총 거래량 및 가장 이른/최신 활동을 나열하세요. $10k를 초과하는 클러스터에 높은 우선순위 검토로 표시하세요.✓ 복사됨

→ 분석가 큐 항목

결과: 정확한 Cypher가 보존된 우선순위가 지정된 사기 검토 큐입니다.

함정

순진한 순회는 허브(10k 사용자가 있는 공유 공개 wifi 기기)에서 폭발합니다 — 깊이를 제한하고 순회 전에 허브 노드를 차수로 필터링하세요

함께 쓰기: postgres

콘텐츠 추천 쿼리 프로토타입 만들기

👤 '사용자가 좋아한' 항목을 빌드하는 제품 엔지니어 ⏱ ~30 min intermediate

언제 쓸까: User-LIKED->Item이 있고 유사한 사용자의 항목을 추천하려고 합니다.

흐름

사용자 선택 및 이웃 찾기

사용자 <id>의 경우 가장 많은 LIKED 항목을 공유하는 20명의 사용자를 찾으세요. user_id와 겹침 개수를 반환하세요.✓ 복사됨

→ 순위가 지정된 유사한 사용자
이 사용자들이 좋아한 항목 추천

상위 20명의 유사한 사용자에 대해 <id>가 좋아하지 않은 항목을 나열하세요. 이를 좋아한 유사한 사용자의 수로 순위를 매기세요.✓ 복사됨

→ 상위 N 추천
재사용 가능한 쿼리로 변환

$user_id로 호출 가능하도록 매개변수화하세요; 속도에 필요한 인덱스를 추가하세요.✓ 복사됨

→ 프로덕션 준비 쿼리 + CREATE INDEX 문

결과: 온라인 제공에 충분히 빠른 작동 가능한 협업 필터링 쿼리입니다.

함정

:User(id)의 인덱스를 잊으면 시작 쿼리가 선형이 됩니다 — CREATE INDEX FOR (u:User) ON (u.id)를 실행하고 EXPLAIN으로 사용되는지 확인하세요

관계형 데이터를 스테이징 테이블에서 Neo4j로 로드하기

👤 SQL에서 그래프로 이동하는 데이터 엔지니어 ⏱ ~40 min advanced

언제 쓸까: Postgres에 사용자 + 팔로우가 있고 그래프 표현을 원합니다.

사전 조건

쓰기 가능한 Neo4j 사용자 — 대상 데이터베이스에 CREATE 권한이 있는 역할

흐름

노드/에지 매핑 계획

users(id, name) 및 follows(from_id, to_id) 테이블이 주어지면 Neo4j 모델을 제안하세요. 레이블? 관계 방향?✓ 복사됨

→ (:User {id,name})-[:FOLLOWS]->(:User)
먼저 제약 조건 생성

CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE를 생성하세요. 실행하세요.✓ 복사됨

→ 제약 조건 생성됨
MERGE로 대량 로드

제공된 사용자 행에서 UNWIND $rows AS r MERGE (:User {id:r.id}) ...를 실행한 다음 MERGE (a)-[:FOLLOWS]->(b)로 팔로우합니다. 한 번에 10k씩 배치합니다.✓ 복사됨

→ 모든 행이 멱등원적으로 로드됨

결과: 관계형 데이터를 그래프 형태로 로드하는 재실행 가능한 ETL입니다.

함정

CREATE 대신 MERGE를 사용하면 다시 실행할 때 중복 노드가 생성됩니다 — 항상 업사이트에 MERGE를 사용하고 속��를 위해 대량 MERGE 전에 고유성 제약 조건을 요구하세요

함께 쓰기: postgres

기술 그래프에서 자연어 질문에 답변하기

👤 도메인 KG가 있는 내부 팀 ⏱ ~25 min intermediate

언제 쓸까: 작은 온톨로지(제품, 기능, 고객)를 구축했고 Cypher를 배우지 않고 Claude가 '기능 X를 사용하는 고객은 누구인가'에 답변하도록 합니다.

흐름

Claude를 스키마로 접지하기

스키마는 다음과 같습니다 [get_neo4j_schema 출력 붙여넣기]. 지금부터 내 질문을 Cypher로 번역한 후 실행하세요.✓ 복사됨

→ Claude가 스키마 이해를 반복합니다
질문하고 Cypher + 답변 받기

지난 분기에 기능 'export-csv'를 사용하는 고객은 누구인가요?✓ 복사됨

→ 표시된 Cypher + 결과 테이블
Cypher가 잘못되었을 때 정제

그 Cypher는 :USED 관계를 Session으로 놓쳤습니다. 세션을 통해 가는 것으로 수정하세요.✓ 복사됨

→ 수정된 Cypher 재실행

결과: 기술 팀원을 위한 경량 NL-to-Cypher 인터페이스입니다.

함정

Claude가 존재하지 않는 레이블을 만듭니다 — 이를 고정하세요: '제공된 스키마의 레이블/관계만 사용하세요; 그렇지 않으면 알 수 없다고 말합니다'

조합

다른 MCP와 조합해 10배 효율

neo4j + postgres

관계형 데이터를 그래프 표현과 동기화하기

Postgres에서 사용자 + 팔로우를 가져온 다음 Neo4j에 (:User)-[:FOLLOWS]->(:User)로 MERGE하세요.✓ 복사됨

neo4j + qdrant

그래프 강화 RAG: 의미론적 회상을 위해 Qdrant, 정확한 관계를 위해 Neo4j 사용

Qdrant는 질문과 유사한 문서를 찾습니다; 그 다음 일치한 엔티티에서 Neo4j를 순회하여 답변을 위한 구조화된 사실을 가져오세요.✓ 복사됨

neo4j + filesystem

Cypher 생성 보고서를 CSV/Markdown으로 내보내기

사기 네트워크 Cypher를 실행하고 상위 50개 클러스터를 /reports/fraud-<date>.csv로 내보내세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
get_neo4j_schema		새 세션에서 항상 먼저	무료
read_neo4j_cypher	query: str, params?: object	모든 MATCH / RETURN — 읽기 전용	무료
write_neo4j_cypher	query: str, params?: object	CREATE/MERGE/SET/DELETE — 뮤테이션	무료

비용 및 제한

운영 비용

API 쿼터: Neo4j 인스턴스로 제한됩니다. Aura Free: 200k 노드/400k 관계.
호출당 토큰: 스키마: ~500 토큰. 쿼리 결과: 행+속성에 따라 다릅니다.
금액: Community / 자체 호스팅의 경우 무료입니다. Aura Free 계층이 있습니다. Aura 유료는 ~$65/월부터 시작합니다.
팁: 항상 큰 그래프에서 먼저 EXPLAIN을 실행하세요; 시작 레이블에 누락된 인덱스는 5ms 쿼리를 5분 스캔으로 바꿉니다.

보안

권한, 시크릿, 파급범위

최소 스코프: 읽기 전용 탐색을 위한 reader 역할

자격 증명 저장: 환경에서 NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD

데이터 외부 송신: Neo4j(자체 호스팅 또는 Aura)에 대한 직접 Bolt 연결

절대 부여 금지: admin 역할 PUBLIC 쓰기 접근

DROP DATABASE 및 CREATE CONSTRAINT는 상승된 역할이 필요합니다 — 이를 별도의 관리자 전용 연결 프로필에 유지하세요.
명시적으로 쓰기가 필요하지 않은 세션의 경우 reader-role 계정으로 MCP를 실행하세요.

문제 해결

자주 발생하는 오류와 해결

ServiceUnavailable: 연결 거부됨

Neo4j가 실행되지 않거나 Bolt 포트가 잘못됨(기본값 7687). cypher-shell -a bolt://host:7687로 확인하세요.

확인: nc -zv host 7687

Neo.ClientError.Security.Unauthorized

사용자명/암호가 잘못되었습니다. 관리자 세션에서 CALL dbms.security.changePassword('new')를 통해 재설정하세요.

Neo.ClientError.Statement.SyntaxError

Claude의 Cypher에 오타가 있습니다 — 정확한 오류를 붙여넣고 수정된 쿼리를 요청하세요.

쓰기 실패: 읽기 전용 모드에서는 쓰기 작업이 허용되지 않습니다

reader 역할로 연결되었습니다; WRITE 권한이 있는 사용자로 전환하거나 별도의 writer 연결을 사용하세요.

대안

Neo4j 다른 것과 비교

대안	언제 쓰나	단점/장점
Memgraph MCP	스트리밍 그래프 분석이 필요합니다; Memgraph는 Cypher 호환입니다	생태계가 더 작고 호스팅 옵션이 더 적습니다
ArangoDB MCP	멀티 모델(그래프 + 문서 + KV)을 원합니다	Cypher 대신 AQL; 학습 곡선
Postgres + Apache AGE	대부분 관계형이고 일부 그래프 요구사항이 있습니다	대규모 순회에서 Neo4j보다 그래프 성능이 더 나쁩니다

Neo4j

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Neo4j

사전 조건

흐름

함정

사전 조건

흐름

함정

흐름

함정

사전 조건

흐름

함정

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Neo4j 다른 것과 비교

더 보기

리소스