Neo4j MCP

Claude(및 기타 MCP 클라이언트)가 Neo4j 그래프 데이터베이스를 쿼리하고 변경할 수 있게 해주는 Model Context Protocol 서버입니다. 독립형 MCP 서버이자 한 번 설치하면 모든 프로젝트에서 재사용할 수 있는 Claude Code 플러그인으로 제공됩니다.

각 프로젝트는 로컬 .env 파일을 통해 자체 Neo4j 자격 증명을 제공하므로, Claude Code가 열린 폴더에 따라 동일한 플러그인이 서로 다른 데이터베이스를 대상으로 할 수 있습니다.

기능

• 명시적인 read / write 모드를 갖춘 통합 cypher_query 도구.

• 스키마 조사: 레이블, 관계 유형 및 속성 키.

• 전체 결과 직렬화 — 노드/관계 element_id, 레이블, 유형 및 Neo4j 시간/공간 값을 보존합니다.

• 잘림 플래그가 포함된 결과 크기 제한 기능으로, 무분별한 MATCH (n) 쿼리가 응답을 폭파하지 않도록 합니다.

• .env를 통한 프로젝트별 자격 증명 (작업 디렉토리에서 python-dotenv로 로드).

• stdio(Claude Code, Claude Desktop, Cursor) 및 SSE와 호환됩니다.

Related MCP server: neo4j-server-remote

사전 요구 사항

• Python 3.10+

• 연결 가능한 Neo4j 데이터베이스 (로컬, Docker 또는 Aura)

• pip (또는 uv, pipx)

Python 패키지 설치

이 플러그인은 neo4j-mcp-server라는 콘솔 스크립트를 호출하므로, 먼저 패키지가 PATH에 있어야 합니다.

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

설치 확인:

which neo4j-mcp-server
neo4j-mcp-server --help

팁: pipx를 사용하는 경우 pipx install -e .를 사용하면 서버를 전역 Python 환경과 격리할 수 있습니다.

Claude Code 플러그인으로 사용하기

저장소에는 .claude-plugin/plugin.json에 플러그인 매니페스트가 포함되어 있습니다. 사용자 수준에서 설치하면 neo4j MCP 서버를 모든 프로젝트의 모든 Claude Code 세션에서 사용할 수 있습니다.

1. 플러그인 설치

Claude Code 내부에서:

/plugin install /absolute/path/to/neo4j-mcp

이렇게 하면 매니페스트가 전역적으로 등록됩니다. (게시된 경우 마켓플레이스를 통해 추가할 수도 있습니다. Claude Code의 플러그인 문서를 참조하세요.)

2. Neo4j와 통신할 프로젝트에 .env 파일 배치

MCP 서버는 Claude Code의 작업 디렉토리를 상속받으므로, python-dotenv가 해당 프로젝트 루트에 있는 .env를 가져옵니다. 폴더가 다르면 데이터베이스도 달라지므로 플러그인을 재구성할 필요가 없습니다.

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

Aura / 암호화된 연결의 경우:

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

인증되지 않은 로컬 인스턴스의 경우 NEO4J_USERNAME 및 NEO4J_PASSWORD를 비워 두세요.

.env를 커밋하지 마세요. 모든 프로젝트의 .gitignore에 추가하세요.

3. Claude Code에서 사용하기

프로젝트를 열고 Claude에게 다음과 같이 질문하세요:

• "이 그래프에 어떤 레이블과 관계 유형이 있나요?"

• "가장 많이 연결된 Person 노드 10개를 찾아줘."

• "2010년에 개봉한 Inception이라는 제목의 Movie 노드를 생성해줘."

Claude는 필요에 따라 cypher_query, get_database_schema, test_database_connection 도구를 호출합니다.

Claude Code 없이 사용하기

동일한 패키지가 모든 MCP 호환 클라이언트에 대해 일반 MCP 서버로 작동합니다.

Claude Desktop / Cursor

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 Cursor MCP 설정에 추가하세요:

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

클라이언트가 프로세스를 시작하는 위치 옆에 .env를 배치하거나 환경 블록에서 NEO4J_* 변수를 내보내어 자격 증명을 설정하세요.

SSE 전송 (웹 클라이언트)

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

독립형 CLI

일회성 테스트를 위해 작은 클라이언트가 번들로 제공됩니다:

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

구성 참조

모든 설정은 환경 변수(또는 작업 디렉토리의 .env 파일)에서 읽어옵니다.

MCP 서버가 노출하는 도구