Graphiti MCP Server

Un marco para construir y consultar grafos de conocimiento con conciencia temporal para agentes de IA.

GitHub

Documentación

Servidor MCP de Graphiti

Graphiti es un framework para construir y consultar grafos de conocimiento con conciencia temporal, específicamente diseñado para agentes de IA que operan en entornos dinámicos. A diferencia de los métodos tradicionales de generación aumentada por recuperación (RAG), Graphiti integra continuamente interacciones de usuarios, datos empresariales estructurados y no estructurados, e información externa en un grafo coherente y consultable. El framework soporta actualizaciones incrementales de datos, recuperación eficiente y consultas históricas precisas sin requerir recomputación completa del grafo, lo que lo hace adecuado para desarrollar aplicaciones de IA interactivas y conscientes del contexto.

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

Características

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

  • Gestión de Episodios: Agregar, recuperar y eliminar episodios (texto, mensajes o datos JSON)
  • Gestión de Entidades: Buscar y gestionar nodos de entidades y relaciones en el grafo de conocimiento
  • Capacidades de Búsqueda: Buscar hechos (aristas) y resúmenes de nodos usando búsqueda semántica e híbrida
  • Gestión de Grupos: Organizar y gestionar grupos de datos relacionados con filtrado por group_id
  • Mantenimiento del Grafo: Limpiar el grafo y reconstruir índices

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

  1. Clona el repositorio de GitHub de Graphiti
git clone https://github.com/getzep/graphiti.git

o

gh repo clone getzep/graphiti

Nota la ruta completa a este directorio.

cd graphiti && pwd

  1. Instala los prerrequisitos de Graphiti.

  2. Configura Claude, Cursor u otro cliente MCP para usar Graphiti con transporte stdio. Consulta la documentación del cliente sobre dónde encontrar sus archivos de configuración MCP.

Instalación

Prerrequisitos

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

Configuración

  1. Clona el repositorio y navega al directorio mcp_server
  2. Usa 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 (predeterminado: demodemo)
  • OPENAI_API_KEY: Clave API de OpenAI (requerida para operaciones de LLM)
  • OPENAI_BASE_URL: URL base opcional para la API de OpenAI
  • MODEL_NAME: Nombre del modelo de OpenAI a usar para operaciones de LLM.
  • SMALL_MODEL_NAME: Nombre del modelo de OpenAI a usar para operaciones de LLM más pequeñas.
  • LLM_TEMPERATURE: Temperatura para respuestas de LLM (0.0-2.0).
  • AZURE_OPENAI_ENDPOINT: URL de endpoint opcional de Azure OpenAI
  • AZURE_OPENAI_DEPLOYMENT_NAME: Nombre de implementación opcional de Azure OpenAI
  • AZURE_OPENAI_API_VERSION: Versión de API opcional de Azure OpenAI
  • AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: Nombre de implementación de embeddings opcional de Azure OpenAI
  • AZURE_OPENAI_EMBEDDING_API_VERSION: Versión de API opcional de Azure OpenAI
  • AZURE_OPENAI_USE_MANAGED_IDENTITY: Uso opcional de Identidades Gestionadas de Azure para autenticación

Puedes establecer estas variables en un archivo .env en el directorio del proyecto.

Ejecutando el Servidor

Para ejecutar el servidor MCP de Graphiti 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 grafo (opcional). Si no se proporciona, el valor predeterminado es "default".
  • --destroy-graph: Si se establece, destruye todos los grafos de Graphiti al inicio.
  • --use-custom-entities: Habilita la extracción de entidades usando los ENTITY_TYPES predefinidos

Implementación con Docker

El servidor MCP de Graphiti se puede implementar usando Docker. El Dockerfile usa uv para la gestión de paquetes, asegurando una instalación consistente de dependencias.

Configuración de Entorno

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

  1. Usando un archivo .env (recomendado):

    • Copia el archivo .env.example proporcionado para crear un archivo .env: 
      cp .env.example .env
    • Edita el archivo .env para establecer tu 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)

  2. Usando variables de entorno directamente:

    • También puedes establecer las variables de entorno al ejecutar el comando de 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 de Neo4j con la siguiente configuración predeterminada:

  • Nombre de usuario: neo4j
  • Contraseña: demodemo
  • URI: bolt://neo4j:7687 (desde dentro de la red de Docker)
  • Configuración de memoria optimizada para uso en desarrollo

Ejecutando con Docker Compose

Inicia 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á tanto la base de datos Neo4j como el servidor MCP de Graphiti. La configuración de Docker:

  • Usa uv para la gestión de paquetes y la ejecución del servidor
  • Instala dependencias desde el archivo pyproject.toml
  • Se conecta al contenedor de Neo4j usando las variables de entorno
  • Expone el servidor en el puerto 8000 para transporte SSE basado en HTTP
  • Incluye un healthcheck para Neo4j para asegurar que esté completamente operativo antes de iniciar el servidor MCP

Integración con Clientes MCP

Configuración

Para usar el servidor MCP de Graphiti con un cliente compatible con MCP, configúralo para conectarse al servidor:

[!IMPORTANTE] Necesitarás el gestor de paquetes de Python, uv instalado. Consulta las instrucciones de instalación de uv.

Asegúrate de establecer la ruta completa al binario de uv y a tu carpeta del proyecto de 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 transporte SSE (basado en HTTP), puedes usar esta configuración:

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

Herramientas Disponibles

El servidor MCP de Graphiti expone las siguientes herramientas:

  • add_episode: Agregar un episodio al grafo de conocimiento (soporta formatos de texto, JSON y mensajes)
  • search_nodes: Buscar en el grafo de conocimiento resúmenes de nodos relevantes
  • search_facts: Buscar en el grafo de conocimiento hechos relevantes (aristas entre entidades)
  • delete_entity_edge: Eliminar una arista de entidad del grafo de conocimiento
  • delete_episode: Eliminar un episodio del grafo de conocimiento
  • get_entity_edge: Obtener una arista de entidad por su UUID
  • get_episodes: Obtener los episodios más recientes para un grupo específico
  • clear_graph: Limpiar todos los datos del grafo de conocimiento y reconstruir índices
  • get_status: Obtener el estado del servidor MCP de Graphiti y la conexión a Neo4j

Trabajando con Datos JSON

El servidor MCP de Graphiti puede procesar datos JSON estructurados a través de 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 Cursor

Para integrar el Servidor MCP de Graphiti con el IDE Cursor, sigue estos pasos:

  1. Ejecuta el servidor MCP de Graphiti usando el transporte SSE:
python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

Sugerencia: especifica un group_id para asignar un espacio de nombres a los datos del grafo. Si no especificas un group_id, el servidor usará "default" como group_id.

o

docker compose up
  1. Configura Cursor para conectarse al servidor MCP de Graphiti.
{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

  1. Agrega las reglas de Graphiti a las Reglas de Usuario de Cursor. Consulta cursor_rules.md para más detalles.

  2. Inicia una sesión de agente en Cursor.

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

Integración con Claude Desktop (Servidor MCP Docker)

El contenedor del Servidor MCP de Graphiti usa el transporte MCP SSE. Claude Desktop no soporta SSE de forma nativa, por lo que necesitarás usar una puerta de enlace como mcp-remote.

  1. Ejecuta el servidor MCP de Graphiti usando transporte SSE:

    docker compose up

  2. (Opcional) Instala mcp-remote globalmente: Si prefieres tener mcp-remote instalado globalmente, o si encuentras problemas con npx al obtener el paquete, puedes instalarlo globalmente. De lo contrario, npx (usado en el siguiente paso) lo manejará por ti.

    npm install -g mcp-remote

  3. Configura Claude Desktop: Abre tu archivo de configuración de Claude Desktop (generalmente claude_desktop_config.json) y agrega o modifica 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 tienes una entrada mcpServers, agrega graphiti-memory (o el nombre que elijas) como una nueva clave dentro de ella.

  4. Reinicia 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 de LLM y embeddings)
  • Cliente compatible con MCP

Licencia

Este proyecto está licenciado bajo la misma licencia que el proyecto padre de Graphiti.