Graphiti

You can run a standalone Graphiti MCP Server to manage a temporally-aware knowledge graph. It supports episode, entity, and graph management, plus flexible transport options for local or remote clients. This guide walks you through installing, configuring, starting the server, and connecting MCP clients.

How to use

Connect your MCP client to the Graphiti MCP Server using one of the available transports. You can run the server locally and access it via standard HTTP, or use a local stdio session for direct-invocation clients. The server exposes tools to add episodes, search nodes and edges, delete items, clear the graph, and rebuild indices. Use a group_id to isolate and organize data for different projects.

How to install

Prerequisites: make sure you have Python 3.10 or higher and a Neo4j database (Neo4j version 5.26 or later). If you plan to use LLM features, have an OpenAI API key ready.

Install from source and run the MCP server locally with Python tooling.

git clone git@github.com:dreamnear/graphiti-mcp.git
cd graphiti-mcp
pip install -e .

Set up runtime configuration by copying the example environment file and editing the values for your Neo4j connection and optional OpenAI API key.

cp .env.example .env

# Required Neo4j configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password_here

# Optional OpenAI API key for LLM operations
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

Start the server directly or via a package manager. Use the command that matches your preference.

# Direct execution
graphiti-mcp-server

# With options
graphiti-mcp-server --model gpt-4.1-mini --transport sse --group-id my_project

If you prefer using uv for package management, install uv, sync dependencies, and run the server.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
uv run graphiti-mcp-server

For containerized deployments, build and run with Docker or Docker Compose.

docker build -t graphiti-mcp-server .
docker run -p 8000:8000 --env-file .env graphiti-mcp-server

docker-compose up

Configuration

Configure the server using environment variables. The important ones are the Neo4j connection and OpenAI API key. You can also tune the LLM model, disable or enable certain features, and control concurrency and host binding.

# Example environment block
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password_here

OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini
LLM_TEMPERATURE=0.0

MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
SEMAPHORE_LIMIT=10

Available runtime arguments include transport, model, group-id, host, port, and path for endpoints. Use these to tailor how clients connect and how the server processes episodes.

Notes on connecting MCP clients

You can connect via HTTP, SSE, or STDIO transports. The STDIO configuration demonstrates how to run the MCP server as a local process with direct command invocation, including the necessary environment variables.

HTTP connection example uses a URL with a group identifier to target a specific data namespace.

Security and maintenance

Keep your Neo4j instance secured and access-controlled. If you expose the MCP server externally, ensure you use appropriate authentication for OpenAI endpoints and limit access to trusted clients. Regularly back up your graph data and monitor the concurrency settings to avoid overload during peak usage.

Available tools

add_memory

Add an episode to the knowledge graph, supporting text, JSON, and message formats.

search_memory_nodes

Search the knowledge graph for relevant node summaries.

search_memory_facts

Search the knowledge graph for relevant facts (edges) between entities.

delete_entity_edge

Delete an entity edge from the knowledge graph.

delete_episode

Delete an episode from the knowledge graph.

get_entity_edge

Retrieve an entity edge by its UUID.

get_episodes

Fetch the most recent episodes for a specific group.

clear_graph

Clear all data from the knowledge graph and rebuild indices.