Neo4j MCP 서버

이는 Neo4j를 지식 그래프 관리를 위한 백엔드 저장소로 사용하는 메모리 제어 프로토콜(MCP) 서버 구현입니다. 그래프 데이터베이스 형식으로 지식을 저장하고 검색하기 위한 stdio 기반 인터페이스를 제공합니다.

필수 조건

파이썬 3.8 이상
Neo4j 데이터베이스(로컬 또는 원격)
Poetry(Python 패키지 관리자)
Docker 및 Docker Compose(Neo4j 실행용)
Go Task(선택 사항, 작업 자동화용)

설치

저장소를 복제합니다.

지엑스피1

아직 Poetry를 설치하지 않았다면 설치하세요.

curl -sSL https://install.python-poetry.org | python3 -

종속성 설치:

poetry install

구성

클로드 데스크톱 구성

Claude Desktop을 실행하는 Ubuntu 사용자의 경우 다음 위치의 Claude Desktop 구성 파일에 MCP 서버를 추가하여 구성할 수 있습니다.

~/.config/Claude/claude_desktop_config.json

구성하기 전에 독립 실행형 실행 파일을 빌드해야 합니다.

task build

이렇게 하면 dist/neo4j_mcp_server 에 바이너리가 생성됩니다. 빌드된 실행 파일을 가리키도록 설정 경로를 업데이트하세요.

example_mcp_config.json 에 구성 예시가 제공됩니다. 이 파일을 복사하여 수정할 수 있습니다.

cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json

그런 다음 구성 파일에서 command 경로를 편집하여 빌드한 실행 파일을 가리키도록 합니다.

{
  "mcpServers": [
    {
      "name": "neo4j-knowledge-graph",
      "command": ["/path/to/your/dist/neo4j_mcp_server"],
      ...
    }
  ]
}

구성에는 다음이 포함됩니다.

서버 이름 및 설명
서버를 시작하는 명령(빌드된 실행 파일의 경로)
사용 가능한 도구 및 매개변수
필수 필드 및 데이터 유형

서버 실행

작업 사용(권장)

Go Task가 설치되어 있으면 제공된 Taskfile을 사용하여 서버를 관리할 수 있습니다.

# Show available tasks
task

# Start everything (Docker + Server)
task run

# Start development environment (Docker + Server + Test)
task dev

# Stop all services
task down

Docker Compose 직접 사용하기

Neo4j 컨테이너를 시작합니다.

docker-compose up -d

Neo4j가 준비될 때까지 기다리세요(컨테이너는 docker ps 에서 "정상"으로 표시됨)

MCP 서버를 직접 실행

다음을 사용하여 서버를 시작합니다.

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

서버는 stdio 모드로 시작하여 MCP 프로토콜 메시지를 수신할 준비를 합니다.

사용 가능한 도구

1. 엔터티 생성

지식 그래프에 새 엔터티를 생성합니다. 각 엔터티는 유형과 속성을 가져야 합니다. ID는 명시적으로 지정하지 않으면 name 속성에서 자동으로 설정됩니다.

매개변수:

entities : 엔티티 객체 목록, 각 엔티티에는 다음이 포함됩니다.
- type : 문자열 - 엔터티의 유형(예: 개인, 조직)
- properties : 개체 - 엔터티 속성의 키-값 쌍('id' 또는 'name'을 포함해야 함)

입력 예시:

{
    "entities": [{
        "type": "Person",
        "properties": {
            "name": "John Doe",
            "occupation": "Developer",
            "age": 30
        }
    }]
}

2. 관계 만들기

지식 그래프에 있는 기존 엔터티 간의 관계를 생성합니다. 관계를 생성하기 전에 참조되는 모든 엔터티가 존재해야 합니다.

매개변수:

relations : 관계 객체 목록, 각각 포함:
- type : 문자열 - 관계의 유형(예: KNOWS, WORKS_FOR)
- from : 문자열 - 소스 엔터티의 ID
- to : 문자열 - 대상 엔터티의 ID

입력 예시:

{
    "relations": [{
        "type": "KNOWS",
        "from": "john_doe",
        "to": "jane_smith"
    }]
}

3. 엔터티 검색

강력한 텍스트 매칭 및 필터링 기능을 사용하여 지식 그래프에서 엔터티를 검색합니다. 텍스트 검색, 유형별 엔터티 나열, 특정 속성을 가진 엔터티 찾기 또는 이러한 필터의 조합에 사용할 수 있습니다.

매개변수:

search_term : 문자열(선택 사항) - 엔터티 속성에서 검색할 텍스트입니다. 지정하지 않으면 다른 필터를 기반으로 엔터티를 반환합니다.
entity_type : 문자열(선택 사항) - 엔터티 유형(예: 개인, 조직)별로 결과를 필터링합니다. 단독으로 제공하면 해당 유형의 모든 엔터티를 반환합니다.
properties : List[String] (선택 사항) - 필터링할 속성 이름 목록:
- search_term을 사용하여: 해당 속성에서 해당 용어를 검색합니다.
- search_term 없이: 다음 속성 중 하나라도 정의된 엔터티를 반환합니다.
include_relationships : Boolean(선택 사항, 기본값: false) - 연결된 엔터티 및 관계를 포함할지 여부
fuzzy_match : Boolean(선택 사항, 기본값: true) - search_term이 제공될 때 대소문자를 구분하지 않는 부분 일치를 사용할지 여부

입력 예시:

// Search by text with type filter
{
    "search_term": "John",
    "entity_type": "Person",
    "properties": ["name", "occupation"],
    "include_relationships": true
}

// List all entities of a type
{
    "entity_type": "Person"
}

// Find entities with specific properties
{
    "properties": ["email", "phone"],
    "entity_type": "Contact"
}

// Combine filters
{
    "entity_type": "Person",
    "properties": ["email"],
    "search_term": "example.com",
    "fuzzy_match": true
}

// Return all entities (no filters)
{}

보고:

{
    "results": [
        {
            "id": "john_doe",
            "type": ["Entity", "Person"],
            "properties": {
                "name": "John Doe",
                "email": "john@example.com"
            },
            "relationships": [  // Only included if include_relationships is true
                {
                    "type": "WORKS_AT",
                    "direction": "outgoing",
                    "node": {
                        "id": "tech_corp",
                        "type": "Company",
                        "properties": {
                            "name": "Tech Corp"
                        }
                    }
                }
            ]
        }
    ]
}

참고사항:

필터가 제공되지 않으면 모든 엔터티를 반환합니다.
엔터티 유형 필터링은 정확한 일치(모호하지 않음)입니다.
속성 존재 여부 확인은 IS NOT NULL 로 수행됩니다.
fuzzy_match가 true인 경우 텍스트 검색은 대소문자를 구분하지 않는 부분 일치를 지원합니다.
빈 결과는 오류가 아닌 빈 배열로 반환됩니다.
성능 고려 사항:
- 유형별 필터링은 텍스트 검색보다 효율적입니다.
- 속성 존재 확인이 최적화되었습니다.
- 모든 속성을 검색하는 대신 특정 속성을 사용하는 것을 고려하세요
- 대규모 결과 세트는 향후 버전에서 페이지별로 구분될 수 있습니다.

4. 엔터티 업데이트

지식 그래프의 기존 엔터티를 업데이트합니다. 속성 및 레이블을 추가/제거할 수 있습니다.

매개변수:

updates : 업데이트 개체 목록, 각 개체에는 다음이 포함됩니다.
- id : 문자열(필수) - 업데이트할 엔터티의 ID
- properties : 객체(선택 사항) - 업데이트하거나 추가할 속성
- remove_properties : List[String] (선택 사항) - 제거할 속성 이름
- add_labels : List[String] (선택 사항) - 엔터티에 추가할 레이블
- remove_labels : List[String] (선택 사항) - 엔터티에서 제거할 레이블

입력 예시:

{
    "updates": [{
        "id": "john_doe",
        "properties": {
            "occupation": "Senior Developer",
            "salary": 100000
        },
        "remove_properties": ["temporary_note"],
        "add_labels": ["Verified"],
        "remove_labels": ["Pending"]
    }]
}

5. 엔터티 삭제

관계의 선택적 계단식 삭제를 통해 지식 그래프에서 엔터티를 삭제합니다.

매개변수:

entity_ids : List[String] (필수) - 삭제할 엔티티 ID 목록
cascade : Boolean (선택 사항, 기본값: false) - 연결된 관계를 삭제할지 여부
dry_run : Boolean(선택 사항, 기본값: false) - 변경하지 않고 삭제 영향을 미리 봅니다.

입력 예시:

{
    "entity_ids": ["john_doe", "jane_smith"],
    "cascade": true,
    "dry_run": true
}

보고:

success : Boolean - 작업이 성공했는지 여부
deleted_entities : 삭제된 엔터티 목록
deleted_relationships : 삭제된 관계 목록
errors : 오류 메시지 목록(있는 경우)
impacted_entities : 영향을 받는 엔터티 목록(dry_run만 해당)
impacted_relationships : 영향을 받을 관계 목록(dry_run 전용)

6. 스키마 내성 검사

노드 레이블, 관계 유형 및 해당 속성을 포함하여 Neo4j 데이터베이스 스키마에 대한 포괄적인 정보를 검색합니다.

매개변수: 필요 없음

보고:

schema : 다음을 포함하는 객체:
- node_labels : 데이터베이스의 모든 노드 레이블 목록
- relationship_types : 모든 관계 유형 목록
- node_properties : 레이블을 속성 이름 목록으로 매핑
- relationship_properties : 관계 유형을 속성 이름 목록으로 매핑

입력 예시:

{}

테스트

테스트 스크립트

이 프로젝트에는 시스템의 다양한 측면에 대한 여러 테스트 스크립트가 포함되어 있습니다.

mcp_neo4j_knowledge_graph/test_mcp_client.py - MCP 클라이언트 기능을 테스트합니다.
- 서버 시작을 확인합니다
- 테스트 도구 목록
- 테스트 스키마 내성
- GXP18 엔티티 생성 테스트
mcp_neo4j_knowledge_graph/test_mcp_config.py - MCP 구성을 테스트합니다.
- 구성 파일 로딩을 검증합니다.
- 공식 MCP SDK를 사용하여 서버 연결을 테스트합니다.
- 필요한 모든 도구가 GXP19에 있는지 확인합니다.
mcp_neo4j_knowledge_graph/test_neo4j_connection.py - Neo4j 데이터베이스 연결을 테스트합니다.
- 데이터베이스 연결을 확인합니다
- 기본 쿼리 기능을 테스트합니다
- GXP20 환경 구성을 확인합니다.

테스트 실행

여러 가지 방법으로 테스트를 실행할 수 있습니다.

모든 테스트를 함께 실행하세요.
task test # Runs all tests including pytest and integration tests
개별 테스트 유형을 실행합니다.
task test-client # Run MCP client test task test-config # Run MCP config test task test-db # Run Neo4j connection test task test-integration # Run integration tests
pytest로 직접 테스트를 실행합니다.
poetry run pytest # Run all pytest-compatible tests

개발

작업 사용

이 프로젝트에는 여러 가지 개발 작업이 포함됩니다.

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

직접 실행

이 프로젝트는 Poetry와 함께 자동으로 설치되는 여러 개발 도구를 사용합니다.

코드 서식을 위한 black
수입 정렬을 위한 isort
린팅용 flake8
테스트를 위한 pytest

Poetry를 사용하여 다음 도구를 실행할 수 있습니다.

# Format code
poetry run black .

# Sort imports
poetry run isort .

# Run linter
poetry run flake8

# Run tests
poetry run pytest

오류 처리

서버에는 다음에 대한 포괄적인 오류 처리 기능이 포함되어 있습니다.

데이터베이스 연결 문제
잘못된 쿼리
누락된 노드
잘못된 요청 형식
스키마 검증 오류
관계 생성 실패
엔티티 업데이트 충돌

모든 오류는 MCP 프로토콜 형식으로 적절한 오류 메시지와 함께 반환됩니다.

Docker 구성

Neo4j 컨테이너는 다음 설정으로 구성됩니다.

포트: 7474(HTTP) 및 7687(Bolt)
기본 자격 증명: neo4j/password
APOC 플러그인이 활성화되었습니다
파일 가져오기/내보내기 활성화됨
상태 확인이 구성되었습니다

docker-compose.yml 파일에서 이러한 설정을 수정할 수 있습니다.

작업 명령 참조

task - 사용 가능한 작업 표시
task run - Docker 및 MCP 서버 시작
task dev - 개발 환경 시작(Docker + Server + Test)
task docker - Neo4j 데이터베이스 시작
task server - MCP 서버 실행
task test - 모든 테스트 실행
task test-client - MCP 클라이언트 테스트 실행
task test-config - MCP 구성 테스트 실행
task test-db - 데이터베이스 테스트 실행
task test-integration - 통합 테스트 실행
task down - 모든 Docker 서비스 중지
task format - black 및 isort를 사용하여 코드 형식 지정
task lint - flake8 linter 실행
task help - 모든 작업에 대한 자세한 도움말을 표시합니다.

Neo4j Knowledge Graph

Integrations

Neo4j MCP 서버

필수 조건

설치

구성

클로드 데스크톱 구성

서버 실행

작업 사용(권장)

Docker Compose 직접 사용하기

MCP 서버를 직접 실행

사용 가능한 도구

1. 엔터티 생성

2. 관계 만들기

3. 엔터티 검색

4. 엔터티 업데이트

5. 엔터티 삭제

6. 스키마 내성 검사

테스트

테스트 스크립트

테스트 실행

개발

작업 사용

직접 실행

오류 처리

Docker 구성

작업 명령 참조

Appeared in Searches