Сервер MCP Graphiti

Graphiti — это фреймворк для построения и запроса графов знаний с учетом времени, специально разработанный для агентов ИИ, работающих в динамических средах. В отличие от традиционных методов генерации дополненного поиска (RAG), Graphiti непрерывно интегрирует пользовательские взаимодействия, структурированные и неструктурированные корпоративные данные и внешнюю информацию в связный, запрашиваемый граф. Фреймворк поддерживает инкрементные обновления данных, эффективный поиск и точные исторические запросы без необходимости полного пересчета графа, что делает его подходящим для разработки интерактивных, контекстно-зависимых приложений ИИ.

Это экспериментальная реализация сервера Model Context Protocol (MCP) для Graphiti. Сервер MCP раскрывает ключевую функциональность Graphiti через протокол MCP, позволяя помощникам ИИ взаимодействовать с возможностями графа знаний Graphiti.

Функции

Сервер Graphiti MCP предоставляет следующие ключевые высокоуровневые функции Graphiti:

Управление эпизодами : добавление, извлечение и удаление эпизодов (текст, сообщения или данные JSON)
Управление сущностями : поиск и управление узлами сущностей и связями в графе знаний.
Возможности поиска : поиск фактов (ребер) и сводок узлов с использованием семантического и гибридного поиска.
Управление группами : организация и управление группами связанных данных с помощью фильтрации group_id.
Обслуживание графика : очистка графика и перестроение индексов.

Быстрый старт для Claude Desktop, Cursor и других клиентов

Клонируйте репозиторий Graphiti GitHub

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

или

gh repo clone getzep/graphiti

Запомните полный путь к этому каталогу.

cd graphiti && pwd

Установите необходимые компоненты Graphiti .
Настройте Claude, Cursor или другой клиент MCP для использования Graphiti с транспортом stdio . См. документацию клиента о том, где найти файлы конфигурации MCP.

Установка

Предпосылки

Убедитесь, что у вас установлен Python 3.10 или выше.
Работающая база данных Neo4j (требуется версия 5.26 или более поздняя)
Ключ API OpenAI для операций LLM

Настраивать

Клонируйте репозиторий и перейдите в каталог 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 : URI для базы данных Neo4j (по умолчанию: bolt://localhost:7687 )
NEO4J_USER : имя пользователя Neo4j (по умолчанию: neo4j )
NEO4J_PASSWORD : пароль Neo4j (по умолчанию: demodemo )
OPENAI_API_KEY : ключ API OpenAI (требуется для операций LLM)
OPENAI_BASE_URL : дополнительный базовый URL-адрес для OpenAI API.
MODEL_NAME : имя модели OpenAI, используемое для операций LLM.
SMALL_MODEL_NAME : имя модели OpenAI, используемое для небольших операций LLM.
LLM_TEMPERATURE : Температура для ответов LLM (0,0–2,0).
AZURE_OPENAI_ENDPOINT : Необязательный URL-адрес конечной точки Azure OpenAI
AZURE_OPENAI_DEPLOYMENT_NAME : Необязательное имя развертывания Azure OpenAI
AZURE_OPENAI_API_VERSION : Необязательная версия API Azure OpenAI
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME : Необязательное имя развертывания внедрения Azure OpenAI
AZURE_OPENAI_EMBEDDING_API_VERSION : Необязательная версия API Azure OpenAI
AZURE_OPENAI_USE_MANAGED_IDENTITY : необязательное использование управляемых удостоверений Azure для аутентификации

Вы можете задать эти переменные в файле .env в каталоге проекта.

Запуск сервера

Чтобы запустить сервер Graphiti MCP напрямую с помощью uv :

uv run graphiti_mcp_server.py

С опциями:

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

Доступные аргументы:

--model : переопределяет переменную среды MODEL_NAME .
--small-model : переопределяет переменную среды SMALL_MODEL_NAME .
--temperature : переопределяет переменную среды LLM_TEMPERATURE .
--transport : Выберите метод транспорта (sse или stdio, по умолчанию: sse)
--group-id : Установить пространство имен для графика (необязательно). Если не указано, по умолчанию используется "default".
--destroy-graph : Если установлено, уничтожает все графы Graphiti при запуске.
--use-custom-entities : включить извлечение сущностей с использованием предопределенных ENTITY_TYPES

Развертывание Docker

Сервер Graphiti MCP можно развернуть с помощью Docker. Dockerfile использует uv для управления пакетами, обеспечивая последовательную установку зависимостей.

Конфигурация среды

Перед запуском настройки Docker Compose вам необходимо настроить переменные среды. У вас есть два варианта:

Использование файла .env (рекомендуется):
- Скопируйте предоставленный файл .env.example , чтобы создать файл .env :
  cp .env.example .env
- Отредактируйте файл .env , чтобы задать ключ API OpenAI и другие параметры конфигурации:
  # 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 с использованием переменных среды
Предоставляет сервер на порту 8000 для HTTP-транспорта SSE
Включает проверку работоспособности Neo4j, чтобы убедиться в его полной работоспособности перед запуском сервера MCP.

Интеграция с клиентами MCP

Конфигурация

Чтобы использовать сервер Graphiti MCP с клиентом, совместимым с MCP, настройте его для подключения к серверу:

[!ВАЖНО] Вам понадобится установленный менеджер пакетов Python, uv . Пожалуйста, ознакомьтесь с инструкциями по установке uv .
Убедитесь, что вы указали полный путь к двоичному файлу uv и папке вашего проекта 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"
      }
    }
  }
}

Для транспорта SSE (на основе HTTP) можно использовать следующую конфигурацию:

{
  "mcpServers": {
    "graphiti-memory": {
      "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 может обрабатывать структурированные данные JSON через инструмент add_episode с source="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"
)

Интеграция с Cursor IDE

Чтобы интегрировать Graphiti MCP Server с Cursor IDE, выполните следующие действия:

Запустите сервер Graphiti MCP с использованием транспорта SSE:

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

Подсказка: укажите group_id для пространства имен графовых данных. Если вы не укажете group_id , сервер будет использовать "default" в качестве group_id.

или

docker compose up

Настройте курсор для подключения к серверу Graphiti MCP.

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

Добавьте правила Graphiti в пользовательские правила Cursor. Подробности см. в cursor_rules.md .
Запустите сеанс агента в Cursor.

Интеграция позволяет помощникам ИИ в Cursor поддерживать постоянную память с помощью возможностей графа знаний Graphiti.

Интеграция с Claude Desktop (Docker MCP Server)

Контейнер Graphiti MCP Server использует транспорт SSE MCP. Claude Desktop изначально не поддерживает SSE, поэтому вам нужно будет использовать шлюз, например mcp-remote .

Запустите сервер Graphiti MCP с использованием транспорта SSE :
docker compose up
(Необязательно) Установите mcp-remote глобально : если вы предпочитаете, чтобы mcp-remote был установлен глобально, или если у вас возникли проблемы с npx при загрузке пакета, вы можете установить его глобально. В противном случае npx (используется на следующем шаге) сделает это за вас.
npm install -g mcp-remote
Настройте Claude Desktop : откройте файл конфигурации Claude Desktop (обычно claude_desktop_config.json ) и добавьте или измените раздел mcpServers следующим образом:
{ "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 ] } } }
Если у вас уже есть запись mcpServers , добавьте в нее graphiti-memory (или выбранное вами имя) в качестве нового ключа.
Перезапустите Claude Desktop , чтобы изменения вступили в силу.

Требования

Python 3.10 или выше
База данных Neo4j (требуется версия 5.26 или более поздняя)
Ключ API OpenAI (для операций LLM и встраиваний)
MCP-совместимый клиент

Лицензия

Данный проект лицензирован по той же лицензии, что и родительский проект Graphiti.

Graphiti MCP Server