Graphiti MCP Server

Um framework para construir e consultar grafos de conhecimento com noção temporal para agentes de IA.

GitHubExperimente este MCPPatrocinado

Documentação

Graphiti MCP Server

Graphiti é um framework para construir e consultar grafos de conhecimento com consciência temporal, especificamente adaptado para agentes de IA que operam em ambientes dinâmicos. Diferentemente dos métodos tradicionais de geração aumentada por recuperação (RAG), o Graphiti integra continuamente interações de usuários, dados empresariais estruturados e não estruturados e informações externas em um grafo coerente e consultável. O framework suporta atualizações incrementais de dados, recuperação eficiente e consultas históricas precisas sem exigir recomputação completa do grafo, tornando-o adequado para o desenvolvimento de aplicações de IA interativas e sensíveis ao contexto.

Esta é uma implementação experimental de servidor Model Context Protocol (MCP) para o Graphiti. O servidor MCP expõe as principais funcionalidades do Graphiti por meio do protocolo MCP, permitindo que assistentes de IA interajam com os recursos de grafo de conhecimento do Graphiti.

Recursos

O servidor MCP do Graphiti expõe as seguintes funções principais de alto nível do Graphiti:

  • Gerenciamento de Episódios: Adicionar, recuperar e excluir episódios (texto, mensagens ou dados JSON)
  • Gerenciamento de Entidades: Pesquisar e gerenciar nós de entidades e relacionamentos no grafo de conhecimento
  • Recursos de Busca: Buscar fatos (arestas) e resumos de nós usando busca semântica e híbrida
  • Gerenciamento de Grupos: Organizar e gerenciar grupos de dados relacionados com filtragem por group_id
  • Manutenção do Grafo: Limpar o grafo e reconstruir índices

Início Rápido para Claude Desktop, Cursor e outros clientes

  1. Clone o repositório do Graphiti no GitHub
git clone https://github.com/getzep/graphiti.git

ou

gh repo clone getzep/graphiti

Anote o caminho completo para este diretório.

cd graphiti && pwd

  1. Instale os pré-requisitos do Graphiti.

  2. Configure o Claude, o Cursor ou outro cliente MCP para usar Graphiti com transporte stdio. Consulte a documentação do cliente para saber onde encontrar os arquivos de configuração MCP.

Instalação

Pré-requisitos

  1. Certifique-se de ter o Python 3.10 ou superior instalado.
  2. Um banco de dados Neo4j em execução (versão 5.26 ou posterior é necessária)
  3. Chave de API da OpenAI para operações de LLM

Configuração

  1. Clone o repositório e navegue até o diretório mcp_server
  2. Use o uv para criar um ambiente virtual e instalar as dependências:
# 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

Configuração

O servidor usa as seguintes variáveis de ambiente:

  • NEO4J_URI: URI do banco de dados Neo4j (padrão: bolt://localhost:7687)
  • NEO4J_USER: nome de usuário do Neo4j (padrão: neo4j)
  • NEO4J_PASSWORD: senha do Neo4j (padrão: demodemo)
  • OPENAI_API_KEY: chave de API da OpenAI (necessária para operações de LLM)
  • OPENAI_BASE_URL: URL base opcional para a API da OpenAI
  • MODEL_NAME: nome do modelo OpenAI a ser usado para operações de LLM.
  • SMALL_MODEL_NAME: nome do modelo OpenAI a ser usado para operações de LLM menores.
  • LLM_TEMPERATURE: temperatura para respostas de LLM (0.0-2.0).
  • AZURE_OPENAI_ENDPOINT: URL de endpoint opcional do Azure OpenAI
  • AZURE_OPENAI_DEPLOYMENT_NAME: nome de implantação opcional do Azure OpenAI
  • AZURE_OPENAI_API_VERSION: versão opcional da API do Azure OpenAI
  • AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: nome de implantação opcional de embeddings do Azure OpenAI
  • AZURE_OPENAI_EMBEDDING_API_VERSION: versão opcional da API do Azure OpenAI
  • AZURE_OPENAI_USE_MANAGED_IDENTITY: uso opcional de Identidades Gerenciadas do Azure para autenticação

Você pode definir essas variáveis em um arquivo .env no diretório do projeto.

Executando o Servidor

Para executar o servidor MCP do Graphiti diretamente usando uv:

uv run graphiti_mcp_server.py

Com opções:

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

Argumentos disponíveis:

  • --model: substitui a variável de ambiente MODEL_NAME.
  • --small-model: substitui a variável de ambiente SMALL_MODEL_NAME.
  • --temperature: substitui a variável de ambiente LLM_TEMPERATURE.
  • --transport: escolha o método de transporte (sse ou stdio, padrão: sse)
  • --group-id: define um namespace para o grafo (opcional). Se não for fornecido, o padrão é "default".
  • --destroy-graph: se definido, destrói todos os grafos do Graphiti na inicialização.
  • --use-custom-entities: ativa a extração de entidades usando os ENTITY_TYPES predefinidos

Implantação com Docker

O servidor MCP do Graphiti pode ser implantado usando Docker. O Dockerfile usa uv para gerenciamento de pacotes, garantindo instalação consistente de dependências.

Configuração de Ambiente

Antes de executar a configuração do Docker Compose, você precisa configurar as variáveis de ambiente. Você tem duas opções:

  1. Usando um arquivo .env (recomendado):

    • Copie o arquivo .env.example fornecido para criar um arquivo .env: 
      cp .env.example .env
    • Edite o arquivo .env para definir sua chave de API da OpenAI e outras opções de configuração: 
      # 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
    • A configuração do Docker Compose está configurada para usar este arquivo se ele existir (é opcional)

  2. Usando variáveis de ambiente diretamente:

    • Você também pode definir as variáveis de ambiente ao executar o comando do Docker Compose: 
      OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Configuração do Neo4j

A configuração do Docker Compose inclui um contêiner Neo4j com a seguinte configuração padrão:

  • Nome de usuário: neo4j
  • Senha: demodemo
  • URI: bolt://neo4j:7687 (de dentro da rede Docker)
  • Configurações de memória otimizadas para uso em desenvolvimento

Executando com Docker Compose

Inicie os serviços usando o Docker Compose:

docker compose up

Ou, se você estiver usando uma versão mais antiga do Docker Compose:

docker-compose up

Isso iniciará tanto o banco de dados Neo4j quanto o servidor MCP do Graphiti. A configuração do Docker:

  • Usa uv para gerenciamento de pacotes e execução do servidor
  • Instala dependências do arquivo pyproject.toml
  • Conecta-se ao contêiner Neo4j usando as variáveis de ambiente
  • Expõe o servidor na porta 8000 para transporte SSE baseado em HTTP
  • Inclui um healthcheck para o Neo4j para garantir que ele esteja totalmente operacional antes de iniciar o servidor MCP

Integração com Clientes MCP

Configuração

Para usar o servidor MCP do Graphiti com um cliente compatível com MCP, configure-o para conectar-se ao servidor:

[!IMPORTANT] Você precisará do gerenciador de pacotes Python, uv, instalado. Consulte as instruções de instalação do uv.

Certifique-se de definir o caminho completo para o binário uv e sua pasta de projeto do 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 (baseado em HTTP), você pode usar esta configuração:

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

Ferramentas Disponíveis

O servidor MCP do Graphiti expõe as seguintes ferramentas:

  • add_episode: adiciona um episódio ao grafo de conhecimento (suporta formatos de texto, JSON e mensagem)
  • search_nodes: busca no grafo de conhecimento resumos de nós relevantes
  • search_facts: busca no grafo de conhecimento fatos relevantes (arestas entre entidades)
  • delete_entity_edge: exclui uma aresta de entidade do grafo de conhecimento
  • delete_episode: exclui um episódio do grafo de conhecimento
  • get_entity_edge: obtém uma aresta de entidade pelo seu UUID
  • get_episodes: obtém os episódios mais recentes de um grupo específico
  • clear_graph: limpa todos os dados do grafo de conhecimento e reconstrói índices
  • get_status: obtém o status do servidor MCP do Graphiti e da conexão com o Neo4j

Trabalhando com Dados JSON

O servidor MCP do Graphiti pode processar dados JSON estruturados por meio da ferramenta add_episode com source="json". Isso permite extrair automaticamente entidades e relacionamentos de dados estruturados:


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

Integração com o Cursor IDE

Para integrar o Graphiti MCP Server com o Cursor IDE, siga estas etapas:

  1. Execute o servidor MCP do Graphiti usando o transporte SSE:
python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

Dica: especifique um group_id para definir o namespace dos dados do grafo. Se você não especificar um group_id, o servidor usará "default" como group_id.

ou

docker compose up
  1. Configure o Cursor para conectar-se ao servidor MCP do Graphiti.
{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

  1. Adicione as regras do Graphiti às Regras do Usuário do Cursor. Consulte cursor_rules.md para obter detalhes.

  2. Inicie uma sessão de agente no Cursor.

A integração permite que assistentes de IA no Cursor mantenham memória persistente por meio dos recursos de grafo de conhecimento do Graphiti.

Integração com Claude Desktop (Docker MCP Server)

O contêiner do Graphiti MCP Server usa o transporte SSE MCP. O Claude Desktop não suporta SSE nativamente, então você precisará usar um gateway como o mcp-remote.

  1. Execute o servidor MCP do Graphiti usando transporte SSE:

    docker compose up

  2. (Opcional) Instale o mcp-remote globalmente: Se você preferir ter o mcp-remote instalado globalmente, ou se encontrar problemas com o npx ao buscar o pacote, você pode instalá-lo globalmente. Caso contrário, o npx (usado na próxima etapa) cuidará disso para você.

    npm install -g mcp-remote

  3. Configure o Claude Desktop: Abra seu arquivo de configuração do Claude Desktop (geralmente claude_desktop_config.json) e adicione ou modifique a seção mcpServers da seguinte forma:

    {
  "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
      ]
    }
  }
}

    Se você já tiver uma entrada mcpServers, adicione graphiti-memory (ou o nome de sua escolha) como uma nova chave dentro dela.

  4. Reinicie o Claude Desktop para que as alterações tenham efeito.

Requisitos

  • Python 3.10 ou superior
  • Banco de dados Neo4j (versão 5.26 ou posterior é necessária)
  • Chave de API da OpenAI (para operações de LLM e embeddings)
  • Cliente compatível com MCP

Licença

Este projeto é licenciado sob a mesma licença do projeto Graphiti original.