> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server.

# Graphiti MCP Server

> Connect Graphiti's Context Graphs to Claude, Cursor, and other MCP clients via the Graphiti MCP server.

#### What is the Graphiti MCP Server?

The Graphiti MCP Server is an experimental implementation that exposes
Graphiti operations through the Model Context Protocol (MCP).

MCP clients can use the server to add episodes, search the graph, manage graph
data, and inspect the server status.

## Supported providers

The server supports these database providers:

* FalkorDB, which is the default provider
* Neo4j

The server supports OpenAI, Azure OpenAI, Anthropic, Gemini, and Groq for LLM
inference. It supports OpenAI, Azure OpenAI, Gemini, and Voyage for embeddings.

## Quick Start

> **Note**
>
> This quick start uses the default OpenAI and FalkorDB configuration. The
> checked-in default LLM model is `gpt-5.5`.

### Prerequisites

Before you start, install or configure:

1. Python 3.10 or later.
2. `uv`.
3. A FalkorDB or Neo4j database.
4. Credentials for the selected LLM and embedding providers.

### Installation

Clone the repository:

```bash
git clone https://github.com/getzep/graphiti.git
cd graphiti
```

Install the MCP server dependencies:

```bash
cd mcp_server
uv sync
```

### Configuration

Command-line arguments override environment variables. Environment variables
override values in `config/config.yaml`.

For the default FalkorDB configuration, set these variables in `.env`:

```bash
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-5.5
FALKORDB_URI=redis://localhost:6379
FALKORDB_PASSWORD=
FALKORDB_DATABASE=default_db
```

For Neo4j, set the connection variables and select the provider when you start
the server:

```bash
OPENAI_API_KEY=your_openai_api_key_here
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password
```

### Running the Server

The default transport is streamable HTTP. Start the server from the
`mcp_server` directory:

```bash
uv run main.py
```

The MCP endpoint is `http://localhost:8000/mcp/`.

Select Neo4j with a command-line argument:

```bash
uv run main.py --database-provider neo4j
```

## MCP Client Integration

The server supports streamable HTTP and `stdio`. The SSE transport remains
available for compatibility, but it is deprecated.

### Claude Desktop

Configure a `stdio` client with the `main.py` entry point:

```json
{
  "mcpServers": {
    "graphiti-context": {
      "transport": "stdio",
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/graphiti/mcp_server",
        "main.py",
        "--transport",
        "stdio",
        "--database-provider",
        "neo4j"
      ],
      "env": {
        "OPENAI_API_KEY": "your_api_key",
        "MODEL_NAME": "gpt-5.5",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}
```

### Cursor IDE

Start the server with the default HTTP transport. Then configure the client to
use the streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "graphiti-context": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}
```

## Available Tools

The server registers these tools:

* `add_memory`
* `search_nodes`
* `search_memory_facts`
* `delete_entity_edge`
* `delete_episode`
* `get_entity_edge`
* `get_episodes`
* `summarize_saga`
* `build_communities`
* `add_triplet`
* `get_episode_entities`
* `clear_graph`
* `get_status`

`clear_graph` clears the selected group IDs. If a request omits the group IDs,
the tool uses the configured default group. The tool requires an effective
group ID.

## Docker Deployment

Run the provided Compose file from the `mcp_server` directory:

```bash
docker compose -f docker/docker-compose.yml up
```

The Compose file starts FalkorDB and the MCP server. The server uses streamable
HTTP at `http://localhost:8000/mcp/`.

## Concurrency and telemetry

The `SEMAPHORE_LIMIT` environment variable controls episode-processing
concurrency. Decrease the value if an LLM provider returns rate-limit errors.

Graphiti sends anonymous initialization telemetry by default. Disable
telemetry with:

```bash
GRAPHITI_TELEMETRY_ENABLED=false
```

## Next Steps

The [MCP Server README](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
contains the complete configuration schema and provider examples.

> **Warning**
>
> The MCP server is experimental and under active development. Features and APIs may change between releases.