Graphiti MCP Server

This repository contains the Graphiti Model Context Protocol (MCP) Server and its associated command-line interface (CLI) tool. It allows AI agents to interact with a knowledge graph for persistent memory, entity extraction, and relationship tracking using the Graphiti framework.

Features

Exposes Graphiti functionality via MCP (SSE or Stdio transport).
Provides tools for adding/searching episodes, nodes, and facts in a knowledge graph.
Supports custom entity type definitions for tailored extraction.
Includes a CLI (graphiti) for project initialization, entity management, and Docker environment control.
Uses Docker Compose for easy deployment of the MCP server(s) and Neo4j database.
Leverages uv for fast dependency management.

Prerequisites

Python: Version 3.10 or higher (python3 --version). Python 3.11+ recommended (as used in Dockerfile).
Docker & Docker Compose: Required to run the Neo4j database and MCP server containers. Install from Docker's official website.
uv: A fast Python package installer and resolver. If you don't have it, install it first (requires pip or curl):

    # Using pip (recommended if you have Python/pip already)

    pip install uv

    # Or using curl

    # curl -LsSf https://astral.sh/uv/install.sh | sh

    # source $HOME/.cargo/env # Or equivalent for your shell if using curl method

    

    # Verify installation

    uv --version

    

Installation and Setup Guide

This guide covers how to install the graphiti CLI and set up the necessary environment. Choose the path that best suits your needs:

1. For Regular Users (Recommended): Install the CLI globally using pipx for managing projects and running services.
2. For Developers: Set up a local development environment using venv if you plan to modify the CLI or server code.

---

1. Standard Installation for Users (Using pipx)

This is the strongly recommended method if you primarily want to use the graphiti CLI to initialize projects, manage entities, and run the Docker services. pipx installs the CLI into an isolated environment, making it available system-wide without interfering with other Python projects.

Why pipx?

Isolation: Prevents dependency conflicts.
Clean Global Environment: Keeps your system Python tidy.
Safety: Avoids issues with sudo pip or modifying system Python.

Python: 3.10+ (python3 --version).
Docker & Docker Compose: Install from Docker's official website.
uv: Follow the instructions in the Prerequisites section above.
pipx: If you don't have it:

    # Install pipx (requires Python and pip)

    python3 -m pip install --user pipx

    # Add pipx to your PATH

    python3 -m pipx ensurepath

    # Close and reopen your terminal, or source your shell profile (e.g., ~/.zshrc, ~/.bashrc)

    

    # Choose a suitable parent directory

    cd ~/dev

    git clone <repository-url> rawr-mcp-graphiti

    cd rawr-mcp-graphiti

    

2. Configure Environment Variables (Optional but Recommended):
Copy the example .env file within the cloned repository:

        # Make sure you are in the cloned repo directory (e.g., ~/dev/rawr-mcp-graphiti)

        cp .env.example .env

        

    # Make sure you are in the cloned repo directory

    pipx install . --include-deps

    

4. First Run & Repo Path Configuration:
The first time you run a graphiti command that needs to access the repository (like graphiti check-setup or graphiti compose), it might not find the repository automatically.
If it can't find it, the CLI will prompt you interactively to enter the absolute path to where you cloned the rawr-mcp-graphiti repository.
Enter the correct absolute path (e.g., /Users/your_user/dev/rawr-mcp-graphiti).
The CLI will validate the path and save it to a configuration file (~/.config/graphiti/repo_path.txt) for future use.

    # Example: Run check-setup from ANY directory after installation

    graphiti check-setup

    # If needed, it will prompt for the repo path here.

    

    # Check where pipx installed it

    which graphiti

    # Should output a path like: /Users/<your_user>/.local/bin/graphiti

# Verify the CLI runs and can find the repo (due to MCP_GRAPHITI_REPO_PATH)

    # Run this from ANY directory (e.g., your home directory cd ~)

    graphiti --help

    graphiti check-setup # This should now work from anywhere without prompting (if configured)

    

6. Updating: To update after pulling changes in the repository:

    # Navigate back to the repository root

    cd /path/to/your/rawr-mcp-graphiti

    # Pull the latest changes

    git pull

    # Upgrade the pipx installation

    pipx upgrade rawr-mcp-graphiti

    # If needed, force a reinstall from the updated source:

    # pipx reinstall --force rawr-mcp-graphiti

    

Summary for Users: Clone the repo, copy/edit .env, install with pipx. Run a command like graphiti check-setup; if prompted, provide the absolute path to the cloned repo. The path will be saved automatically for future use.

---

2. Local Development Installation (Using venv)

Follow these steps only if you intend to modify or contribute to the graphiti CLI or the MCP server codebase itself. This setup uses a Python virtual environment (.venv) and an editable installation, allowing code changes to be reflected immediately when running graphiti within the activated environment.

Prerequisites:

Same as for Standard Installation (Python, Docker, uv). pipx is not required for this method.

    git clone <repository-url> rawr-mcp-graphiti

    cd rawr-mcp-graphiti

    

2. Configure Environment:
Copy the example environment file:

        cp .env.example .env

        

3. Set up Python Virtual Environment:

    # Create the virtual environment

    python3 -m venv .venv

    # Activate it (example for macOS/Linux)

    source .venv/bin/activate

    # You should see (.venv) in your prompt

    

4. Install Dependencies:
Use uv to install dependencies from the lock file into the active venv.

    # Make sure (.venv) is active

    uv pip sync uv.lock

    

5. Install CLI in Editable Mode:
Install the package itself in editable mode (-e). This links the graphiti command within the venv directly to your source code.

    # Make sure (.venv) is active

    pip install -e .

    # ('uv pip install -e .' should also work)

    

6. Verify Installation:

    # Verify it's using the venv path

    which graphiti

    # Should output path inside your .venv/bin/

# Verify the CLI runs (ensure venv is active)

    graphiti --help

    graphiti check-setup # Run from repo root

    

Summary for Developers: Clone, copy/edit .env, set up .venv, activate it, uv pip sync, pip install -e .. Run commands from within the repo root with the venv active. The repo path will be auto-detected or prompted for and saved on first use.

---

Understanding Which graphiti You're Using

Global (pipx): If no (.venv) is in your prompt, you're likely using the pipx version. It relies on the path stored in ~/.config/graphiti/repo_path.txt (or prompts on first use). Updates require pipx upgrade.
Local (venv): If (.venv) is in your prompt (after source .venv/bin/activate), you're using the editable development version. Code changes are live. Ideally, run from the repo root. Deactivate with deactivate.

---

Verifying Your Setup

Regardless of the installation method, use check-setup.

If using pipx: Run graphiti check-setup from any directory. It relies on the configured path in ~/.config/graphiti/repo_path.txt (or prompts).
If using venv: Activate the venv (source .venv/bin/activate) and run graphiti check-setup from the repository root directory.

```bash