Servidor Graphiti MCP

Graphiti es un marco para crear y consultar grafos de conocimiento con conciencia temporal, diseñado específicamente para agentes de IA que operan en entornos dinámicos. A diferencia de los métodos tradicionales de recuperación-generación aumentada (RAG), Graphiti integra continuamente las interacciones del usuario, datos empresariales estructurados y no estructurados, e información externa en un grafo coherente y consultable. El marco admite actualizaciones incrementales de datos, recuperación eficiente y consultas históricas precisas sin necesidad de recálculo completo del grafo, lo que lo hace ideal para el desarrollo de aplicaciones de IA interactivas y contextuales.

Esta es una implementación experimental del servidor del Protocolo de Contexto de Modelo (MCP) para Graphiti. El servidor MCP expone la funcionalidad clave de Graphiti a través del protocolo MCP, lo que permite a los asistentes de IA interactuar con las capacidades del grafo de conocimiento de Graphiti.

Características

El servidor Graphiti MCP expone las siguientes funciones clave de alto nivel de Graphiti:

Gestión de episodios : agregue, recupere y elimine episodios (texto, mensajes o datos JSON)
Gestión de entidades : busque y administre nodos de entidades y relaciones en el gráfico de conocimiento
Capacidades de búsqueda : Busque hechos (bordes) y resúmenes de nodos mediante búsqueda semántica e híbrida
Gestión de grupos : organice y administre grupos de datos relacionados con el filtrado group_id
Mantenimiento de gráficos : Limpiar el gráfico y reconstruir los índices

Inicio rápido para Claude Desktop, Cursor y otros clientes

Clonar el repositorio de Graphiti en GitHub

git clone https://github.com/getzep/graphiti.git

gh repo clone getzep/graphiti

Anote la ruta completa a este directorio.

cd graphiti && pwd

Instalar los requisitos previos de Graphiti .
Configure Claude, Cursor u otro cliente MCP para usar Graphiti con un transporte stdio . Consulte la documentación del cliente para saber dónde encontrar sus archivos de configuración de MCP.

Instalación

Prerrequisitos

Asegúrese de tener instalado Python 3.10 o superior.
Una base de datos Neo4j en ejecución (se requiere la versión 5.26 o posterior)
Clave API de OpenAI para operaciones LLM

Configuración

Clona el repositorio y navega al directorio mcp_server
Utilice uv para crear un entorno virtual e instalar dependencias:

# 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

Configuración

El servidor utiliza las siguientes variables de entorno:

NEO4J_URI : URI para la base de datos Neo4j (predeterminado: bolt://localhost:7687 )
NEO4J_USER : nombre de usuario de Neo4j (predeterminado: neo4j )
NEO4J_PASSWORD : Contraseña de Neo4j (predeterminada: demodemo )
OPENAI_API_KEY : Clave API de OpenAI (necesaria para operaciones LLM)
OPENAI_BASE_URL : URL base opcional para la API OpenAI
MODEL_NAME : Nombre del modelo OpenAI que se utilizará para las operaciones LLM.
SMALL_MODEL_NAME : Nombre del modelo OpenAI que se utilizará para operaciones LLM más pequeñas.
LLM_TEMPERATURE : Temperatura para las respuestas LLM (0,0-2,0).
AZURE_OPENAI_ENDPOINT : URL del punto de conexión de Azure OpenAI opcional
AZURE_OPENAI_DEPLOYMENT_NAME : Nombre de implementación de Azure OpenAI opcional
AZURE_OPENAI_API_VERSION : Versión opcional de la API de Azure OpenAI
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME : Nombre de implementación de incrustación de Azure OpenAI opcional
AZURE_OPENAI_EMBEDDING_API_VERSION : Versión opcional de la API de Azure OpenAI
AZURE_OPENAI_USE_MANAGED_IDENTITY : Uso opcional de identidades administradas de Azure para la autenticación

Puede configurar estas variables en un archivo .env en el directorio del proyecto.

Ejecución del servidor

Para ejecutar el servidor Graphiti MCP directamente usando uv :

uv run graphiti_mcp_server.py

Con opciones:

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

Argumentos disponibles:

--model : anula la variable de entorno MODEL_NAME .
--small-model : anula la variable de entorno SMALL_MODEL_NAME .
--temperature : anula la variable de entorno LLM_TEMPERATURE .
--transport : elige el método de transporte (sse o stdio, predeterminado: sse)
--group-id : Establece un espacio de nombres para el gráfico (opcional). Si no se proporciona, el valor predeterminado es "default".
--destroy-graph : si se configura, destruye todos los gráficos de Graphiti al iniciarse.
--use-custom-entities : Habilitar la extracción de entidades utilizando los ENTITY_TYPES predefinidos

Implementación de Docker

El servidor Graphiti MCP se puede implementar con Docker. El Dockerfile utiliza uv para la gestión de paquetes, lo que garantiza una instalación consistente de las dependencias.

Configuración del entorno

Antes de ejecutar la configuración de Docker Compose, debe configurar las variables de entorno. Tiene dos opciones:

Usando un archivo .env (recomendado):
- Copie el archivo .env.example proporcionado para crear un archivo .env :
  cp .env.example .env
- Edite el archivo .env para configurar su clave API de OpenAI y otras opciones de configuración:
  # 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
- La configuración de Docker Compose está configurada para usar este archivo si existe (es opcional)
Usando variables de entorno directamente :
- También puedes configurar las variables de entorno al ejecutar el comando Docker Compose:
  OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Configuración de Neo4j

La configuración de Docker Compose incluye un contenedor Neo4j con la siguiente configuración predeterminada:

Nombre de usuario: neo4j
Contraseña: demodemo
URI: bolt://neo4j:7687 (desde dentro de la red Docker)
Configuraciones de memoria optimizadas para uso en desarrollo

Ejecutar con Docker Compose

Inicie los servicios usando Docker Compose:

docker compose up

O si estás usando una versión anterior de Docker Compose:

docker-compose up

Esto iniciará la base de datos Neo4j y el servidor Graphiti MCP. Configuración de Docker:

Utiliza uv para la gestión de paquetes y la ejecución del servidor.
Instala dependencias del archivo pyproject.toml
Se conecta al contenedor Neo4j mediante las variables de entorno
Expone el servidor en el puerto 8000 para el transporte SSE basado en HTTP
Incluye una comprobación del estado de Neo4j para garantizar que esté completamente operativo antes de iniciar el servidor MCP

Integración con clientes MCP

Configuración

Para utilizar el servidor Graphiti MCP con un cliente compatible con MCP, configúrelo para que se conecte al servidor:

[!IMPORTANTE] Necesitará tener instalado el gestor de paquetes de Python, uv . Consulte las instrucciones de instalación uv .
Asegúrese de configurar la ruta completa al binario uv y a la carpeta de su proyecto Graphiti.

{
  "mcpServers": {
    "graphiti-memory": {
      "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"
      }
    }
  }
}

Para el transporte SSE (basado en HTTP), puede utilizar esta configuración:

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

Herramientas disponibles

El servidor Graphiti MCP expone las siguientes herramientas:

add_episode : agrega un episodio al gráfico de conocimiento (admite formatos de texto, JSON y mensajes)
search_nodes : Busca en el gráfico de conocimiento resúmenes de nodos relevantes
search_facts : Busca en el gráfico de conocimiento hechos relevantes (bordes entre entidades)
delete_entity_edge : elimina un borde de entidad del gráfico de conocimiento
delete_episode : Eliminar un episodio del gráfico de conocimiento
get_entity_edge : Obtener el borde de una entidad por su UUID
get_episodes : Obtener los episodios más recientes de un grupo específico
clear_graph : Borra todos los datos del gráfico de conocimiento y reconstruye los índices
get_status : obtiene el estado del servidor Graphiti MCP y la conexión Neo4j

Trabajar con datos JSON

El servidor Graphiti MCP puede procesar datos JSON estructurados mediante la herramienta add_episode con source="json" . Esto permite extraer automáticamente entidades y relaciones de datos estructurados:

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"
)

Integración con el IDE de Cursor

Para integrar el servidor Graphiti MCP con Cursor IDE, siga estos pasos:

Ejecute el servidor Graphiti MCP utilizando el transporte SSE:

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

Consejo: especifique un group_id para los datos del gráfico del espacio de nombres. Si no lo group_id , el servidor usará "default" como group_id.

docker compose up

Configure Cursor para conectarse al servidor Graphiti MCP.

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Añade las reglas de Graphiti a las reglas de usuario de Cursor. Consulta cursor_rules.md para más detalles.
Inicie una sesión de agente en Cursor.

La integración permite que los asistentes de IA en Cursor mantengan una memoria persistente a través de las capacidades de gráficos de conocimiento de Graphiti.

Integración con Claude Desktop (Docker MCP Server)

El contenedor del servidor Graphiti MCP utiliza el transporte SSE MCP. Claude Desktop no es compatible con SSE de forma nativa, por lo que deberá usar una puerta de enlace como mcp-remote .

Ejecute el servidor Graphiti MCP utilizando el transporte SSE :
docker compose up
(Opcional) Instalar mcp-remote globalmente : Si prefiere tener mcp-remote instalado globalmente o si tiene problemas con npx al obtener el paquete, puede instalarlo globalmente. De lo contrario, npx (usado en el siguiente paso) se encargará de ello.
npm install -g mcp-remote
Configurar Claude Desktop : abra el archivo de configuración de Claude Desktop (normalmente claude_desktop_config.json ) y agregue o modifique la sección mcpServers de la siguiente manera:
{ "mcpServers": { "graphiti-memory": { // You can choose a different name if you prefer "command": "npx", // Or the full path to mcp-remote if npx is not in your PATH "args": [ "mcp-remote", "http://localhost:8000/sse" // Ensure this matches your Graphiti server's SSE endpoint ] } } }
Si ya tiene una entrada mcpServers , agregue graphiti-memory (o el nombre elegido) como una nueva clave dentro de ella.
Reinicie Claude Desktop para que los cambios surtan efecto.

Requisitos

Python 3.10 o superior
Base de datos Neo4j (se requiere versión 5.26 o posterior)
Clave API de OpenAI (para operaciones e incrustaciones LLM)
Cliente compatible con MCP

Licencia

Este proyecto tiene la misma licencia que el proyecto principal Graphiti.

Graphiti MCP Server