Graphiti

Graphiti MCP Server exposes Graphiti’s knowledge graph capabilities through the MCP protocol, letting AI assistants interact with episodes, entities, and graph data in a scalable, persistent way. You can manage episodes, search for entities and facts, organize data with groups, and rebuild or clear the graph as needed, all via MCP clients that communicate over stdio or SSE transport.

How to use

You connect an MCP client to the Graphiti MCP Server using either a local stdio connection or an HTTP-based SSE transport. With stdio, you run the server process locally and communicate through a persistent, in-process channel. With SSE, you send requests over HTTP to a running service endpoint. Use the available tools to add episodes, search for nodes or facts, manage edges, and perform graph maintenance like clearing and rebuilding indices.

How to install

Prerequisites: ensure you have Python 3.10 or higher, a running Neo4j database (version 5.26 or later), and an OpenAI API key for LLM operations.

1. Clone or obtain the Graphiti MCP Server sources if you have access to the project directory.

2. Install the required Python dependencies and set up the environment. If you use a virtual environment manager, prepare it before installing packages.

MCP connections and configuration

The MCP server can be accessed in two ways. The first is a local stdio connection powered by uv, and the second is an HTTP SSE transport exposed at a local URL. Use the stdio configuration when you want a direct, local process communication path, and use the SSE configuration for HTTP-based clients.

If you want to run the stdio-connected server directly from your development machine, use the following command structure and arguments to start the server through uv.

{
  "type": "stdio",
  "name": "graphiti_mcp",
  "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": [
    {"name": "NEO4J_URI", "value": "bolt://localhost:7687"},
    {"name": "NEO4J_USER", "value": "neo4j"},
    {"name": "NEO4J_PASSWORD", "value": "password"},
    {"name": "OPENAI_API_KEY", "value": "YOUR_OPENAI_API_KEY"},
    {"name": "MODEL_NAME", "value": "gpt-4.1-mini"}
  ]
}

Configuring the server for HTTP SSE transport

If you prefer HTTP-based communication, you can connect via SSE at the provided endpoint. The example URL is http://localhost:8000/sse, and your MCP client should connect to that URL using the SSE transport.

{
  "type": "http",
  "name": "graphiti_http",
  "url": "http://localhost:8000/sse",
  "args": []
}

Environment variables and options

Set the following environment variables to configure the server and its connections. You can place these in a .env file in your project directory or export them in your environment before starting the server.

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
OPENAI_API_KEY=sk-XXXXXXXX
MODEL_NAME=gpt-4.1-mini
OPENAI_BASE_URL=https://api.openai.com/v1
LLM_TEMPERATURE=0.7

Available tools and operations

You can use the following MCP tools to interact with Graphiti’s knowledge graph. Each tool performs a distinct operation on episodes, entities, or graph structure.

- add_episode: Add an episode to the knowledge graph (text, JSON, or messages)
- search_nodes: Retrieve node summaries from the graph
- search_facts: Find relevant facts (edges between entities)
- delete_entity_edge: Remove a specific entity edge
- delete_episode: Remove an episode by its identifier
- get_entity_edge: Retrieve an entity edge by UUID
- get_episodes: Get recent episodes for a given group
- clear_graph: Clear all data and rebuild indices
- get_status: Check server and Neo4j health/status

Security and maintenance notes

Keep your OpenAI API key confidential and never expose it in client configurations. Use secure environment management for all credentials. Regularly restart the MCP server during maintenance windows and monitor the health of the Neo4j instance to ensure the graph remains consistent and performant.

Available tools

add_episode

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

search_nodes

Search the knowledge graph for relevant node summaries.

search_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

Get an entity edge by its UUID.

get_episodes

Get the most recent episodes for a specific group.

clear_graph

Clear all data from the knowledge graph and rebuild indices.

get_status

Get the status of the Graphiti MCP server and Neo4j connection.