Graphiti MCP 서버

Graphiti는 동적 환경에서 작동하는 AI 에이전트에 맞춰 시간 인식 지식 그래프를 구축하고 쿼리하는 프레임워크입니다. 기존의 검색 증강 생성(RAG) 방식과 달리 Graphiti는 사용자 상호작용, 정형 및 비정형 엔터프라이즈 데이터, 그리고 외부 정보를 일관성 있고 쿼리 가능한 그래프로 지속적으로 통합합니다. 이 프레임워크는 전체 그래프 재계산 없이 증분형 데이터 업데이트, 효율적인 검색, 그리고 정확한 과거 쿼리를 지원하므로, 대화형 상황 인식 AI 애플리케이션 개발에 적합합니다.

이는 Graphiti를 위한 실험적인 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. MCP 서버는 MCP 프로토콜을 통해 Graphiti의 주요 기능을 제공하여 AI 비서가 Graphiti의 지식 그래프 기능과 상호 작용할 수 있도록 합니다.

특징

Graphiti MCP 서버는 Graphiti의 다음과 같은 주요 고급 기능을 제공합니다.

에피소드 관리 : 에피소드(텍스트, 메시지 또는 JSON 데이터)를 추가, 검색 및 삭제합니다.
엔티티 관리 : 지식 그래프에서 엔티티 노드 및 관계를 검색하고 관리합니다.
검색 기능 : 의미 검색 및 하이브리드 검색을 사용하여 사실(에지) 및 노드 요약 검색
그룹 관리 : group_id 필터링을 통해 관련 데이터 그룹을 구성하고 관리합니다.
그래프 유지 관리 : 그래프를 지우고 인덱스를 다시 작성합니다.

Claude Desktop, Cursor 및 기타 클라이언트를 위한 빠른 시작

Graphiti GitHub 저장소를 복제하세요

지엑스피1

또는

gh repo clone getzep/graphiti

이 디렉토리의 전체 경로를 기록해 두세요.

cd graphiti && pwd

Graphiti 필수 구성 요소를 설치합니다.
Claude, Cursor 또는 다른 MCP 클라이언트가 Graphiti를 stdio 전송과 함께 사용하도록 구성합니다. 클라이언트 설명서에서 MCP 구성 파일의 위치를 확인하세요.

설치

필수 조건

Python 3.10 이상이 설치되어 있는지 확인하세요.
실행 중인 Neo4j 데이터베이스(버전 5.26 이상 필요)
LLM 작업을 위한 OpenAI API 키

설정

저장소를 복제하고 mcp_server 디렉토리로 이동합니다.
uv 사용하여 가상 환경을 만들고 종속성을 설치합니다.

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies in one step
uv sync

구성

서버는 다음과 같은 환경 변수를 사용합니다.

NEO4J_URI : Neo4j 데이터베이스의 URI(기본값: bolt://localhost:7687 )
NEO4J_USER : Neo4j 사용자 이름(기본값: neo4j )
NEO4J_PASSWORD : Neo4j 비밀번호 (기본값: demodemo )
OPENAI_API_KEY : OpenAI API 키(LLM 작업에 필요)
OPENAI_BASE_URL : OpenAI API의 선택적 기본 URL
MODEL_NAME : LLM 추론에 사용할 선택적 모델 이름
AZURE_OPENAI_ENDPOINT : 선택적 Azure OpenAI 엔드포인트 URL
AZURE_OPENAI_DEPLOYMENT_NAME : 선택적 Azure OpenAI 배포 이름
AZURE_OPENAI_API_VERSION : 선택적 Azure OpenAI API 버전
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME : 선택적 Azure OpenAI 임베딩 배포 이름
AZURE_OPENAI_EMBEDDING_API_VERSION : 선택적 Azure OpenAI API 버전
AZURE_OPENAI_USE_MANAGED_IDENTITY : 인증을 위해 Azure 관리 ID를 선택적으로 사용합니다.

프로젝트 디렉토리의 .env 파일에 이러한 변수를 설정할 수 있습니다.

서버 실행

uv 사용하여 Graphiti MCP 서버를 직접 실행하려면:

uv run graphiti_mcp_server.py

옵션:

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

사용 가능한 인수:

--model : LLM 클라이언트와 함께 사용할 모델 이름을 지정합니다.
--transport : 전송 방식(sse 또는 stdio, 기본값: sse)을 선택합니다.
--group-id : 그래프에 대한 네임스페이스를 설정합니다(선택 사항)
--destroy-graph : 모든 Graphiti 그래프를 파괴합니다(주의해서 사용하세요)
--use-custom-entities : 미리 정의된 ENTITY_TYPES를 사용하여 엔티티 추출을 활성화합니다.

도커 배포

Graphiti MCP 서버는 Docker를 사용하여 배포할 수 있습니다. Dockerfile은 패키지 관리를 위해 uv 사용하여 일관된 종속성 설치를 보장합니다.

환경 구성

Docker Compose 설치를 실행하기 전에 환경 변수를 구성해야 합니다. 두 가지 옵션이 있습니다.

.env 파일 사용 (권장):
- 제공된 .env.example 파일을 복사하여 .env 파일을 만듭니다.
  cp .env.example .env
- .env 파일을 편집하여 OpenAI API 키 및 기타 구성 옵션을 설정합니다.
  # Required for LLM operations OPENAI_API_KEY=your_openai_api_key_here MODEL_NAME=gpt-4.1-mini # Optional: OPENAI_BASE_URL only needed for non-standard OpenAI endpoints # OPENAI_BASE_URL=https://api.openai.com/v1
- Docker Compose 설정은 이 파일이 있는 경우 이를 사용하도록 구성됩니다(선택 사항).
환경 변수를 직접 사용하기 :
- Docker Compose 명령을 실행할 때 환경 변수를 설정할 수도 있습니다.
  OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Neo4j 구성

Docker Compose 설정에는 다음과 같은 기본 구성을 갖춘 Neo4j 컨테이너가 포함됩니다.

사용자 이름: neo4j
비밀번호: demodemo
URI: bolt://neo4j:7687 (Docker 네트워크 내부에서)
개발용으로 최적화된 메모리 설정

Docker Compose로 실행

Docker Compose를 사용하여 서비스를 시작합니다.

docker compose up

또는 이전 버전의 Docker Compose를 사용하는 경우:

docker-compose up

이렇게 하면 Neo4j 데이터베이스와 Graphiti MCP 서버가 모두 시작됩니다. Docker 설정:

패키지 관리 및 서버 실행을 위해 uv 사용합니다.
pyproject.toml 파일에서 종속성을 설치합니다.
환경 변수를 사용하여 Neo4j 컨테이너에 연결합니다.
HTTP 기반 SSE 전송을 위해 포트 8000에서 서버를 노출합니다.
MCP 서버를 시작하기 전에 Neo4j가 완전히 작동하는지 확인하기 위한 상태 점검이 포함되어 있습니다.

MCP 클라이언트와 통합

구성

MCP 호환 클라이언트와 함께 Graphiti MCP 서버를 사용하려면 서버에 연결하도록 구성하세요.

[!중요] Python 패키지 관리자인 uv 설치되어 있어야 합니다. uv 설치 지침을 참조하세요.
uv 바이너리와 Graphiti 프로젝트 폴더의 전체 경로를 설정했는지 확인하세요.

{
  "mcpServers": {
    "graphiti": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>>/dev/zep/graphiti/mcp_server",
        "--project",
        ".",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

SSE 전송(HTTP 기반)의 경우 다음 구성을 사용할 수 있습니다.

{
  "mcpServers": {
    "graphiti": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

사용 가능한 도구

Graphiti MCP 서버는 다음 도구를 제공합니다.

add_episode : 지식 그래프에 에피소드 추가(텍스트, JSON, 메시지 형식 지원)
search_nodes : 지식 그래프에서 관련 노드 요약을 검색합니다.
search_facts : 지식 그래프에서 관련 사실(엔터티 간 에지)을 검색합니다.
delete_entity_edge : 지식 그래프에서 엔티티 에지를 삭제합니다.
delete_episode : 지식 그래프에서 에피소드를 삭제합니다.
get_entity_edge : UUID로 엔티티 에지를 가져옵니다.
get_episodes : 특정 그룹의 최신 에피소드를 가져옵니다.
clear_graph : 지식 그래프에서 모든 데이터를 지우고 인덱스를 다시 작성합니다.
get_status : Graphiti MCP 서버와 Neo4j 연결의 상태를 가져옵니다.

JSON 데이터 작업

Graphiti MCP 서버는 add_episode 도구의 source="json" 을 사용하여 구조화된 JSON 데이터를 처리할 수 있습니다. 이를 통해 구조화된 데이터에서 엔티티와 관계를 자동으로 추출할 수 있습니다.

add_episode(
name="Customer Profile",
episode_body="{\"company\": {\"name\": \"Acme Technologies\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\"}, {\"id\": \"P002\", \"name\": \"DataMiner\"}]}",
source="json",
source_description="CRM data"
)

커서 IDE와 통합

Graphiti MCP 서버를 Cursor IDE와 통합하려면 다음 단계를 따르세요.

SSE 전송을 사용하여 Graphiti MCP 서버를 실행합니다.

python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

힌트: 이전 그래프 데이터를 유지하려면 group_id 지정하세요. group_id 지정하지 않으면 서버가 새 그래프를 생성합니다.

Graphiti MCP 서버에 연결하도록 커서를 구성합니다.

{
  "mcpServers": {
    "Graphiti": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Graphiti 규칙을 커서 사용자 규칙에 추가하세요. 자세한 내용은 cursor_rules.md를 참조하세요.
Cursor에서 에이전트 세션을 시작합니다.

이 통합을 통해 Cursor의 AI 어시스턴트는 Graphiti의 지식 그래프 기능을 통해 지속적인 메모리를 유지할 수 있습니다.

요구 사항

Python 3.10 이상
Neo4j 데이터베이스(버전 5.26 이상 필요)
OpenAI API 키(LLM 작업 및 임베딩용)
MCP 호환 클라이언트

특허

이 프로젝트는 Graphiti 프로젝트와 동일한 라이센스에 따라 라이센스가 부여되었습니다.

Graphiti MCP Server

Integrations