# Graphiti MCP Server
Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents
operating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti
continuously integrates user interactions, structured and unstructured enterprise data, and external information into a
coherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical
queries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI
applications.
This is an experimental Model Context Protocol (MCP) server implementation for Graphiti. The MCP server exposes
Graphiti's key functionality through the MCP protocol, allowing AI assistants to interact with Graphiti's knowledge
graph capabilities.
## Features
The Graphiti MCP server exposes the following key high-level functions of Graphiti:
- **Episode Management**: Add, retrieve, and delete episodes (text, messages, or JSON data)
- **Entity Management**: Search and manage entity nodes and relationships in the knowledge graph
- **Search Capabilities**: Search for facts (edges) and node summaries using semantic and hybrid search
- **Group Management**: Organize and manage groups of related data with group_id filtering
- **Graph Maintenance**: Clear the graph and rebuild indices
- **Flexible Ollama Configuration**: Fully configurable LLM and embedding models via CLI arguments and environment variables
## Quick Start
### 🚀 Install from PyPI (Recommended)
The fastest way to get started is using `uvx` to install and run from PyPI:
```bash
# Install and run with default settings
uvx montesmakes.graphiti-memory
# Run with custom configuration
uvx montesmakes.graphiti-memory --transport stdio --group-id my-project
```
📖 **For detailed uvx usage and configuration options, see [UVXUSAGE.md](UVXUSAGE.md)**
### 🛠️ Development Installation
For development or to run from source:
```bash
git clone https://github.com/mandelbro/graphiti-memory.git
cd graphiti/mcp_server
```
Or with GitHub CLI:
```bash
gh repo clone mandelbro/graphiti-memory
cd graphiti/mcp_server
```
### For Claude Desktop and other `stdio` only clients
1. Note the full path to this directory.
```
cd graphiti && pwd
```
2. Install the [Graphiti prerequisites](#prerequisites).
3. Configure Claude, Cursor, or other MCP client to use [Graphiti with a `stdio` transport](#integrating-with-mcp-clients). See the client documentation on where to find their MCP configuration files.
### For Cursor and other `sse`-enabled clients
1. Change directory to the `mcp_server` directory
`cd graphiti/mcp_server`
2. Start the service using Docker Compose
`docker compose up`
3. Point your MCP client to `http://localhost:8020/sse`
## Installation
### Quick Start with uvx (Recommended)
The fastest way to get started is using `uvx` to run the server directly:
```bash
# Install and run with default settings
uvx montesmakes.graphiti-memory
# Run with custom configuration
uvx montesmakes.graphiti-memory --transport stdio --group-id my-project
# For detailed uvx usage, see UVXUSAGE.md
```
### Prerequisites
1. Ensure you have Python 3.10 or higher installed.
2. A running Neo4j database (version 5.26 or later required)
3. **Ollama** installed and running (default) OR OpenAI API key for LLM operations
### Ollama Setup (Default)
The server now defaults to using Ollama for LLM operations and embeddings. To set up Ollama:
1. **Install Ollama**: Visit [https://ollama.ai](https://ollama.ai) for installation instructions
2. **Start Ollama**: Run `ollama serve` to start the Ollama server
3. **Pull required models**:
```bash
ollama pull deepseek-r1:7b # LLM model
ollama pull nomic-embed-text # Embedding model
```
The server will automatically connect to Ollama at `http://localhost:11434/v1` and use these models by default.
### OpenAI Setup (Alternative)
If you prefer to use OpenAI instead of Ollama:
1. Set the environment variable: `USE_OLLAMA=false`
2. Configure your OpenAI API key: `OPENAI_API_KEY=your_api_key_here`
3. Optionally customize the models using `MODEL_NAME` and `SMALL_MODEL_NAME` environment variables
### Docker Setup
The project includes Docker Compose configuration for easy deployment. There are several ways to configure Ollama with Docker:
#### Option 1: Use Host Ollama (Recommended)
If you have Ollama running on your host machine:
1. **Start Ollama on your host**:
```bash
ollama serve
```
2. **Pull required models**:
```bash
ollama pull deepseek-r1:7b
ollama pull nomic-embed-text
```
3. **Start the services**:
```bash
docker compose up
```
The server will connect to your host Ollama instance using `host.docker.internal:11434`.
**Note**: The Graphiti core library requires an `OPENAI_API_KEY` environment variable even when using Ollama (for the reranker component). The Docker configuration includes a dummy API key (`abc`) for this purpose.
#### Option 2: Use Containerized Ollama
If you prefer to run Ollama in a container:
1. **Uncomment the Ollama service** in `docker-compose.yml`:
```yaml
ollama:
image: ollama/ollama:latest
ports:
- "11434:11434"
volumes:
- ollama_data:/root/.ollama
```
2. **Update the OLLAMA_BASE_URL** in the environment section:
```yaml
environment:
- OLLAMA_BASE_URL=http://ollama:11434/v1
```
3. **Uncomment the volume**:
```yaml
volumes:
ollama_data:
```
4. **Start the services**:
```bash
docker compose up
```
5. **Pull models in the container**:
```bash
docker compose exec ollama ollama pull deepseek-r1:7b
docker compose exec ollama ollama pull nomic-embed-text
```
#### Option 3: Use OpenAI with Docker
To use OpenAI instead of Ollama in Docker:
1. **Create a `.env` file** with your OpenAI configuration:
```bash
USE_OLLAMA=false
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4o-mini
```
2. **Update docker-compose.yml** to use the `.env` file:
```yaml
env_file:
- .env
```
3. **Start the services**:
```bash
docker compose up
```
### Local Development Setup
1. **Clone the repository**:
```bash
git clone <repository-url>
cd mcp_server
```
2. **Install dependencies**:
```bash
uv sync
```
3. **Set up environment variables** (optional):
```bash
cp .env.example .env
# Edit .env with your configuration
```
4. **Start Neo4j** (if using Docker):
```bash
docker compose up neo4j -d
```
5. **Run the server**:
```bash
uv run src/graphiti_mcp_server.py --transport sse
```
## Configuration
The server supports multiple configuration methods with the following precedence (highest to lowest):
1. **CLI arguments** (highest priority)
2. **Environment variables**
3. **YAML configuration files**
4. **Default values** (lowest priority)
### Configuration Methods
#### YAML Configuration Files (Recommended)
For complex configurations, you can use YAML files in the `config/` directory:
```yaml
# config/providers/ollama.yml
llm:
model: "deepseek-r1:7b"
base_url: "http://localhost:11434/v1"
temperature: 0.1
max_tokens: 8192
model_parameters:
num_ctx: 4096 # Context window size
num_predict: -1 # Number of tokens to predict
repeat_penalty: 1.1 # Penalty for repeating tokens
top_k: 40 # Limit token selection to top K
top_p: 0.9 # Cumulative probability cutoff
```
See the [config/README.md](config/README.md) for detailed information about YAML configuration.
#### Environment Variables
The server uses the following environment variables:
- `NEO4J_URI`: URI for the Neo4j database (default: `bolt://localhost:7687`)
- `NEO4J_USER`: Neo4j username (default: `neo4j`)
- `NEO4J_PASSWORD`: Neo4j password (default: `demodemo`)
### LLM Configuration
The server now defaults to using **Ollama** for LLM operations and embeddings. You can configure it using these environment variables:
#### Ollama Configuration (Default)
- `USE_OLLAMA`: Use Ollama for LLM and embeddings (default: `true`)
- `OLLAMA_BASE_URL`: Ollama base URL (default: `http://localhost:11434/v1`)
- `OLLAMA_LLM_MODEL`: Ollama LLM model name (default: `deepseek-r1:7b`)
- `OLLAMA_EMBEDDING_MODEL`: Ollama embedding model name (default: `nomic-embed-text`)
- `OLLAMA_EMBEDDING_DIM`: Ollama embedding dimension (default: `768`)
- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)
**Ollama Model Parameters:** You can now configure Ollama-specific model parameters like `num_ctx`, `top_p`, `repeat_penalty`, etc. using YAML configuration files. This provides fine-grained control over model behavior that wasn't previously available through environment variables alone.
#### OpenAI Configuration (Alternative)
To use OpenAI instead of Ollama, set `USE_OLLAMA=false` and configure:
- `OPENAI_API_KEY`: OpenAI API key (required for LLM operations)
- `OPENAI_BASE_URL`: Optional base URL for OpenAI API
- `MODEL_NAME`: OpenAI model name to use for LLM operations (default: `gpt-4.1-mini`)
- `SMALL_MODEL_NAME`: OpenAI model name to use for smaller LLM operations (default: `gpt-4.1-nano`)
- `LLM_TEMPERATURE`: Temperature for LLM responses (0.0-2.0)
- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)
#### Azure OpenAI Configuration (Alternative)
To use Azure OpenAI, set `USE_OLLAMA=false` and configure:
- `AZURE_OPENAI_ENDPOINT`: Azure OpenAI LLM endpoint URL
- `AZURE_OPENAI_DEPLOYMENT_NAME`: Azure OpenAI LLM deployment name
- `AZURE_OPENAI_API_VERSION`: Azure OpenAI LLM API version
- `AZURE_OPENAI_EMBEDDING_API_KEY`: Azure OpenAI Embedding deployment key (if different from `OPENAI_API_KEY`)
- `AZURE_OPENAI_EMBEDDING_ENDPOINT`: Azure OpenAI Embedding endpoint URL
- `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`: Azure OpenAI embedding deployment name
- `AZURE_OPENAI_EMBEDDING_API_VERSION`: Azure OpenAI API version
- `AZURE_OPENAI_USE_MANAGED_IDENTITY`: Use Azure Managed Identities for authentication
- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)
#### General Configuration
- `SEMAPHORE_LIMIT`: Episode processing concurrency. See [Concurrency and LLM Provider 429 Rate Limit Errors](#concurrency-and-llm-provider-429-rate-limit-errors)
- `MCP_SERVER_PORT`: Port for the MCP server when using SSE transport (default: 8020)
You can set these variables in a `.env` file in the project directory. A sample configuration file (`sample_env.txt`) is provided with all available options and their default values.
## Running the Server
To run the Graphiti MCP server directly using `uv`:
```bash
uv run src/graphiti_mcp_server.py
```
With options:
```bash
uv run src/graphiti_mcp_server.py --model gpt-4.1-mini --transport sse
```
Available arguments:
- `--model`: Overrides the `MODEL_NAME` environment variable (only when not using Ollama).
- `--small-model`: Overrides the `SMALL_MODEL_NAME` environment variable (only when not using Ollama).
- `--temperature`: Overrides the `LLM_TEMPERATURE` environment variable.
- `--max-tokens`: Overrides the `LLM_MAX_TOKENS` environment variable.
- `--transport`: Choose the transport method (sse or stdio, default: sse)
- `--port`: Port to bind the MCP server to (default: 8020)
- `--group-id`: Set a namespace for the graph (optional). If not provided, defaults to "default".
- `--destroy-graph`: If set, destroys all Graphiti graphs on startup.
- `--use-custom-entities`: Enable entity extraction using the predefined ENTITY_TYPES
#### Ollama Configuration Arguments
- `--use-ollama`: Use Ollama for LLM and embeddings (default: true)
- `--ollama-base-url`: Ollama base URL (default: http://localhost:11434/v1)
- `--ollama-llm-model`: Ollama LLM model name (default: deepseek-r1:7b)
- `--ollama-embedding-model`: Ollama embedding model name (default: nomic-embed-text)
- `--ollama-embedding-dim`: Ollama embedding dimension (default: 768)
### Ollama Configuration Examples
The Graphiti MCP server provides flexible configuration options for Ollama models. Here are some common use cases:
#### Basic Configuration Examples
**Use default models:**
```bash
# With default .env configuration
uv run src/graphiti_mcp_server.py
# Or explicitly set in .env file:
# USE_OLLAMA=true
# OLLAMA_LLM_MODEL=deepseek-r1:7b
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```
**Use a different LLM model:**
```bash
uv run src/graphiti_mcp_server.py --ollama-llm-model llama3.2:3b
```
**Use a different embedding model with custom dimension:**
```bash
uv run src/graphiti_mcp_server.py --ollama-embedding-model all-minilm-l6-v2 --ollama-embedding-dim 384
```
**Use custom max tokens for larger responses:**
```bash
uv run src/graphiti_mcp_server.py --max-tokens 32768
```
**Connect to a remote Ollama server:**
```bash
uv run src/graphiti_mcp_server.py --ollama-base-url http://remote-server:11434/v1 --ollama-llm-model llama3.2:8b
```
#### Environment Variable Configuration
You can also configure Ollama models using environment variables in a `.env` file:
```bash
# Create or edit .env file
nano .env
```
Add the following variables to your `.env` file:
```env
# Ollama Configuration
OLLAMA_LLM_MODEL=mistral:7b
OLLAMA_EMBEDDING_MODEL=all-minilm-l6-v2
OLLAMA_EMBEDDING_DIM=384
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=32768
```
Then run the server:
```bash
uv run src/graphiti_mcp_server.py
```
#### Configuration Priority
The configuration system follows this priority order (highest to lowest):
1. **CLI arguments** - Override all other settings
2. **Environment variables** - Provide defaults that can be overridden by CLI
3. **Default values** - Built-in defaults for all settings
#### Available Ollama Models
**Common LLM Models:**
- `deepseek-r1:7b` (default) - Good balance of performance and quality
- `llama3.2:3b` - Fast, smaller model for development
- `llama3.2:8b` - Higher quality, larger model
- `mistral:7b` - Excellent performance for many tasks
- `codellama:7b` - Specialized for code generation
- `phi3:3.8b` - Microsoft's efficient model
**Common Embedding Models:**
- `nomic-embed-text` (default) - High-quality embeddings
- `nomic-embed-text-v2` - Improved version of the default
- `all-minilm-l6-v2` - Fast, efficient embeddings
- `all-MiniLM-L6-v2` - Alternative spelling for the same model
- `text-embedding-ada-002` - OpenAI-compatible embeddings
#### Performance Considerations
- **Smaller models** (3B parameters) are faster but may have lower quality
- **Larger models** (7B+ parameters) provide better quality but require more resources
- **Embedding dimensions** affect both performance and storage requirements
- **Remote Ollama servers** can be used for distributed deployments
### Concurrency and LLM Provider 429 Rate Limit Errors
Graphiti's ingestion pipelines are designed for high concurrency, controlled by the `SEMAPHORE_LIMIT` environment variable.
By default, `SEMAPHORE_LIMIT` is set to `10` concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try lowering this value.
If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion performance.
### Docker Deployment
The Graphiti MCP server can be deployed using Docker. The Dockerfile uses `uv` for package management, ensuring
consistent dependency installation.
#### Environment Configuration
Before running the Docker Compose setup, you need to configure the environment variables. You have two options:
1. **Using a .env file** (recommended):
- Copy the provided `.env.example` file to create a `.env` file:
```bash
cp .env.example .env
```
- Edit the `.env` file to set your OpenAI API key and other configuration options:
```
# 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
```
- The Docker Compose setup is configured to use this file if it exists (it's optional)
2. **Using environment variables directly**:
- You can also set the environment variables when running the Docker Compose command:
```bash
OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
```
#### Neo4j Configuration
The Docker Compose setup includes a Neo4j container with the following default configuration:
- Username: `neo4j`
- Password: `demodemo`
- URI: `bolt://neo4j:7687` (from within the Docker network)
- Memory settings optimized for development use
#### Running with Docker Compose
A Graphiti MCP container is available at: `zepai/knowledge-graph-mcp`. The latest build of this container is used by the Compose setup below.
Start the services using Docker Compose:
```bash
docker compose up
```
Or if you're using an older version of Docker Compose:
```bash
docker-compose up
```
This will start both the Neo4j database and the Graphiti MCP server. The Docker setup:
- Uses `uv` for package management and running the server
- Installs dependencies from the `pyproject.toml` file
- Connects to the Neo4j container using the environment variables
- Exposes the server on port 8020 for HTTP-based SSE transport
- Includes a healthcheck for Neo4j to ensure it's fully operational before starting the MCP server
## Integrating with MCP Clients
### Configuration
To use the Graphiti MCP server with an MCP-compatible client, configure it to connect to the server:
> [!IMPORTANT]
> You will need the Python package manager, `uv` installed. Please refer to the [`uv` install instructions](https://docs.astral.sh/uv/getting-started/installation/).
>
> Ensure that you set the full path to the `uv` binary and your Graphiti project folder.
#### Using Ollama (Default)
**Basic Ollama configuration:**
```json
{
"mcpServers": {
"graphiti-memory": {
"transport": "stdio",
"command": "/Users/<user>/.local/bin/uv",
"args": [
"run",
"--isolated",
"--directory",
"/Users/<user>/dev/graphiti-memory",
"--project",
".",
"src/graphiti_mcp_server.py",
"--transport",
"stdio"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password"
}
}
}
}
```
**Custom Ollama models via CLI arguments:**
```json
{
"mcpServers": {
"graphiti-memory": {
"transport": "stdio",
"command": "/Users/<user>/.local/bin/uv",
"args": [
"run",
"--isolated",
"--directory",
"/Users/<user>/dev/graphiti-memory",
"--project",
".",
"src/graphiti_mcp_server.py",
"--transport",
"stdio",
"--ollama-llm-model",
"llama3.2:3b",
"--ollama-embedding-model",
"all-minilm-l6-v2",
"--ollama-embedding-dim",
"384"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password"
}
}
}
}
```
**Custom Ollama models via environment variables:**
```json
{
"mcpServers": {
"graphiti-memory": {
"transport": "stdio",
"command": "/Users/<user>/.local/bin/uv",
"args": [
"run",
"--isolated",
"--directory",
"/Users/<user>/dev/graphiti-memory",
"--project",
".",
"src/graphiti_mcp_server.py",
"--transport",
"stdio"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password",
"OLLAMA_LLM_MODEL": "mistral:7b",
"OLLAMA_EMBEDDING_MODEL": "nomic-embed-text-v2",
"OLLAMA_EMBEDDING_DIM": "768",
"LLM_TEMPERATURE": "0.1",
"LLM_MAX_TOKENS": "32768"
}
}
}
}
```
#### Using OpenAI (Alternative)
```json
{
"mcpServers": {
"graphiti-memory": {
"transport": "stdio",
"command": "/Users/<user>/.local/bin/uv",
"args": [
"run",
"--isolated",
"--directory",
"/Users/<user>/dev/graphiti-memory",
"--project",
".",
"src/graphiti_mcp_server.py",
"--transport",
"stdio"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password",
"USE_OLLAMA": "false",
"OPENAI_API_KEY": "sk-XXXXXXXX",
"MODEL_NAME": "gpt-4.1-mini"
}
}
}
}
```
For SSE transport (HTTP-based), you can use this configuration:
```json
{
"mcpServers": {
"graphiti-memory": {
"transport": "sse",
"url": "http://localhost:8020/sse"
}
}
}
```
## Available Tools
The Graphiti MCP server exposes the following 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
## Working with JSON Data
The Graphiti MCP server can process structured JSON data through the `add_episode` tool with `source="json"`. This
allows you to automatically extract entities and relationships from structured data:
```
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"
)
```
## Integrating with the Cursor IDE
To integrate the Graphiti MCP Server with the Cursor IDE, follow these steps:
1. Run the Graphiti MCP server using the SSE transport:
```bash
python src/graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>
```
Hint: specify a `group_id` to namespace graph data. If you do not specify a `group_id`, the server will use "default" as the group_id.
or
```bash
docker compose up
```
2. Configure Cursor to connect to the Graphiti MCP server.
```json
{
"mcpServers": {
"graphiti-memory": {
"url": "http://localhost:8020/sse"
}
}
}
```
3. Add the Graphiti rules to Cursor's User Rules. See [cursor_rules.md](cursor_rules.md) for details.
4. Kick off an agent session in Cursor.
The integration enables AI assistants in Cursor to maintain persistent memory through Graphiti's knowledge graph
capabilities.
## Integrating with Claude Desktop (Docker MCP Server)
The Graphiti MCP Server container uses the SSE MCP transport. Claude Desktop does not natively support SSE, so you'll need to use a gateway like `mcp-remote`.
1. **Run the Graphiti MCP server using SSE transport**:
```bash
docker compose up
```
2. **(Optional) Install `mcp-remote` globally**:
If you prefer to have `mcp-remote` installed globally, or if you encounter issues with `npx` fetching the package, you can install it globally. Otherwise, `npx` (used in the next step) will handle it for you.
```bash
npm install -g mcp-remote
```
3. **Configure Claude Desktop**:
Open your Claude Desktop configuration file (usually `claude_desktop_config.json`) and add or modify the `mcpServers` section as follows:
```json
{
"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:8020/sse" // Ensure this matches your Graphiti server's SSE endpoint
]
}
}
}
```
If you already have an `mcpServers` entry, add `graphiti-memory` (or your chosen name) as a new key within it.
4. **Restart Claude Desktop** for the changes to take effect.
## Troubleshooting
### Ollama Configuration Issues
**Server won't start with Ollama:**
- Ensure Ollama is installed and running: `ollama serve`
- Check that required models are pulled: `ollama list`
- Verify Ollama server is accessible: `curl http://localhost:11434/v1/models`
- Check your `.env` file has `USE_OLLAMA=true` (default)
**Model not found errors:**
- Pull the required model: `ollama pull <model-name>`
- Check model name spelling (case-sensitive)
- Verify model is available in Ollama library
**Embedding dimension mismatch:**
- Ensure `OLLAMA_EMBEDDING_DIM` matches your embedding model's output dimension
- Common dimensions: 384 (all-minilm-l6-v2), 768 (nomic-embed-text), 1536 (nomic-embed-text-v2)
**Performance issues:**
- Try smaller models for faster response times
- Adjust `SEMAPHORE_LIMIT` for concurrency control
- Consider using remote Ollama servers for distributed workloads
### General Issues
**Neo4j connection errors:**
- Verify Neo4j is running and accessible
- Check connection credentials and URI
- Ensure Neo4j version is 5.26 or later
**MCP client connection issues:**
- Verify transport method (stdio vs sse) matches client requirements
- Check port configuration for SSE transport
- Ensure firewall allows connections on configured ports
## Requirements
- Python 3.10 or higher
- Neo4j database (version 5.26 or later required)
- **Ollama** installed and running (default) OR OpenAI API key (for LLM operations)
- MCP-compatible client
## Telemetry
The Graphiti MCP server uses the Graphiti core library, which includes anonymous telemetry collection. When you initialize the Graphiti MCP server, anonymous usage statistics are collected to help improve the framework.
### What's Collected
- Anonymous identifier and system information (OS, Python version)
- Graphiti version and configuration choices (LLM provider, database backend, embedder type)
- **No personal data, API keys, or actual graph content is ever collected**
### How to Disable
To disable telemetry in the MCP server, set the environment variable:
```bash
export GRAPHITI_TELEMETRY_ENABLED=false
```
Or add it to your `.env` file:
```
GRAPHITI_TELEMETRY_ENABLED=false
```
For complete details about what's collected and why, see the [Telemetry section in the main Graphiti README](../README.md#telemetry).
## 📦 Distribution and Publishing
This project is automatically published to PyPI using GitHub Actions and trusted publishing:
- **PyPI**: https://pypi.org/project/montesmakes.graphiti-memory/
- **Installation**: `uvx montesmakes.graphiti-memory` or `uv tool install montesmakes.graphiti-memory`
### For Maintainers
- **Release Process**: Use `scripts/prepare-release.sh` to prepare new releases
- **Publishing Setup**: See [docs/PYPI_SETUP.md](docs/PYPI_SETUP.md) for complete PyPI configuration
- **Manual Testing**: Use the "Manual Package Test" GitHub Action workflow
Releases are automatically published to PyPI when a new GitHub release is created. TestPyPI deployment happens automatically on pushes to the `main` branch.
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
1. **Clone the repository**:
```bash
git clone https://github.com/mandelbro/graphiti-memory.git
cd graphiti/mcp_server
```
2. **Install dependencies**:
```bash
uv sync --extra dev
```
3. **Run tests**:
```bash
uv run pytest
```
4. **Format and lint**:
```bash
uv run ruff format
uv run ruff check
```
## License
This project is licensed under the same license as the parent Graphiti project.
Raw data
{
"_id": null,
"home_page": null,
"name": "montesmakes.graphiti-memory",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "agents, ai, graphiti, knowledge-graph, mcp, memory",
"author": null,
"author_email": "Made byMontes <chris@montesmakes.co>",
"download_url": "https://files.pythonhosted.org/packages/63/a3/bf03ca1e12fa2e4e1509bc17b19cf271ed2d340b8ed76e0d452d905c9ee0/montesmakes_graphiti_memory-0.4.3.tar.gz",
"platform": null,
"description": "# Graphiti MCP Server\n\nGraphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents\noperating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti\ncontinuously integrates user interactions, structured and unstructured enterprise data, and external information into a\ncoherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical\nqueries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI\napplications.\n\nThis is an experimental Model Context Protocol (MCP) server implementation for Graphiti. The MCP server exposes\nGraphiti's key functionality through the MCP protocol, allowing AI assistants to interact with Graphiti's knowledge\ngraph capabilities.\n\n## Features\n\nThe Graphiti MCP server exposes the following key high-level functions of Graphiti:\n\n- **Episode Management**: Add, retrieve, and delete episodes (text, messages, or JSON data)\n- **Entity Management**: Search and manage entity nodes and relationships in the knowledge graph\n- **Search Capabilities**: Search for facts (edges) and node summaries using semantic and hybrid search\n- **Group Management**: Organize and manage groups of related data with group_id filtering\n- **Graph Maintenance**: Clear the graph and rebuild indices\n- **Flexible Ollama Configuration**: Fully configurable LLM and embedding models via CLI arguments and environment variables\n\n## Quick Start\n\n### \ud83d\ude80 Install from PyPI (Recommended)\n\nThe fastest way to get started is using `uvx` to install and run from PyPI:\n\n```bash\n# Install and run with default settings\nuvx montesmakes.graphiti-memory\n\n# Run with custom configuration\nuvx montesmakes.graphiti-memory --transport stdio --group-id my-project\n```\n\n\ud83d\udcd6 **For detailed uvx usage and configuration options, see [UVXUSAGE.md](UVXUSAGE.md)**\n\n### \ud83d\udee0\ufe0f Development Installation\n\nFor development or to run from source:\n\n```bash\ngit clone https://github.com/mandelbro/graphiti-memory.git\ncd graphiti/mcp_server\n```\n\nOr with GitHub CLI:\n```bash\ngh repo clone mandelbro/graphiti-memory\ncd graphiti/mcp_server\n```\n\n### For Claude Desktop and other `stdio` only clients\n\n1. Note the full path to this directory.\n\n```\ncd graphiti && pwd\n```\n\n2. Install the [Graphiti prerequisites](#prerequisites).\n\n3. Configure Claude, Cursor, or other MCP client to use [Graphiti with a `stdio` transport](#integrating-with-mcp-clients). See the client documentation on where to find their MCP configuration files.\n\n### For Cursor and other `sse`-enabled clients\n\n1. Change directory to the `mcp_server` directory\n\n`cd graphiti/mcp_server`\n\n2. Start the service using Docker Compose\n\n`docker compose up`\n\n3. Point your MCP client to `http://localhost:8020/sse`\n\n## Installation\n\n### Quick Start with uvx (Recommended)\n\nThe fastest way to get started is using `uvx` to run the server directly:\n\n```bash\n# Install and run with default settings\nuvx montesmakes.graphiti-memory\n\n# Run with custom configuration\nuvx montesmakes.graphiti-memory --transport stdio --group-id my-project\n\n# For detailed uvx usage, see UVXUSAGE.md\n```\n\n### Prerequisites\n\n1. Ensure you have Python 3.10 or higher installed.\n2. A running Neo4j database (version 5.26 or later required)\n3. **Ollama** installed and running (default) OR OpenAI API key for LLM operations\n\n### Ollama Setup (Default)\n\nThe server now defaults to using Ollama for LLM operations and embeddings. To set up Ollama:\n\n1. **Install Ollama**: Visit [https://ollama.ai](https://ollama.ai) for installation instructions\n2. **Start Ollama**: Run `ollama serve` to start the Ollama server\n3. **Pull required models**:\n ```bash\n ollama pull deepseek-r1:7b # LLM model\n ollama pull nomic-embed-text # Embedding model\n ```\n\nThe server will automatically connect to Ollama at `http://localhost:11434/v1` and use these models by default.\n\n### OpenAI Setup (Alternative)\n\nIf you prefer to use OpenAI instead of Ollama:\n\n1. Set the environment variable: `USE_OLLAMA=false`\n2. Configure your OpenAI API key: `OPENAI_API_KEY=your_api_key_here`\n3. Optionally customize the models using `MODEL_NAME` and `SMALL_MODEL_NAME` environment variables\n\n### Docker Setup\n\nThe project includes Docker Compose configuration for easy deployment. There are several ways to configure Ollama with Docker:\n\n#### Option 1: Use Host Ollama (Recommended)\n\nIf you have Ollama running on your host machine:\n\n1. **Start Ollama on your host**:\n ```bash\n ollama serve\n ```\n\n2. **Pull required models**:\n ```bash\n ollama pull deepseek-r1:7b\n ollama pull nomic-embed-text\n ```\n\n3. **Start the services**:\n ```bash\n docker compose up\n ```\n\nThe server will connect to your host Ollama instance using `host.docker.internal:11434`.\n\n**Note**: The Graphiti core library requires an `OPENAI_API_KEY` environment variable even when using Ollama (for the reranker component). The Docker configuration includes a dummy API key (`abc`) for this purpose.\n\n#### Option 2: Use Containerized Ollama\n\nIf you prefer to run Ollama in a container:\n\n1. **Uncomment the Ollama service** in `docker-compose.yml`:\n ```yaml\n ollama:\n image: ollama/ollama:latest\n ports:\n - \"11434:11434\"\n volumes:\n - ollama_data:/root/.ollama\n ```\n\n2. **Update the OLLAMA_BASE_URL** in the environment section:\n ```yaml\n environment:\n - OLLAMA_BASE_URL=http://ollama:11434/v1\n ```\n\n3. **Uncomment the volume**:\n ```yaml\n volumes:\n ollama_data:\n ```\n\n4. **Start the services**:\n ```bash\n docker compose up\n ```\n\n5. **Pull models in the container**:\n ```bash\n docker compose exec ollama ollama pull deepseek-r1:7b\n docker compose exec ollama ollama pull nomic-embed-text\n ```\n\n#### Option 3: Use OpenAI with Docker\n\nTo use OpenAI instead of Ollama in Docker:\n\n1. **Create a `.env` file** with your OpenAI configuration:\n ```bash\n USE_OLLAMA=false\n OPENAI_API_KEY=your_openai_api_key_here\n MODEL_NAME=gpt-4o-mini\n ```\n\n2. **Update docker-compose.yml** to use the `.env` file:\n ```yaml\n env_file:\n - .env\n ```\n\n3. **Start the services**:\n ```bash\n docker compose up\n ```\n\n### Local Development Setup\n\n1. **Clone the repository**:\n ```bash\n git clone <repository-url>\n cd mcp_server\n ```\n\n2. **Install dependencies**:\n ```bash\n uv sync\n ```\n\n3. **Set up environment variables** (optional):\n ```bash\n cp .env.example .env\n # Edit .env with your configuration\n ```\n\n4. **Start Neo4j** (if using Docker):\n ```bash\n docker compose up neo4j -d\n ```\n\n5. **Run the server**:\n ```bash\n uv run src/graphiti_mcp_server.py --transport sse\n ```\n\n## Configuration\n\nThe server supports multiple configuration methods with the following precedence (highest to lowest):\n1. **CLI arguments** (highest priority)\n2. **Environment variables**\n3. **YAML configuration files**\n4. **Default values** (lowest priority)\n\n### Configuration Methods\n\n#### YAML Configuration Files (Recommended)\n\nFor complex configurations, you can use YAML files in the `config/` directory:\n\n```yaml\n# config/providers/ollama.yml\nllm:\n model: \"deepseek-r1:7b\"\n base_url: \"http://localhost:11434/v1\"\n temperature: 0.1\n max_tokens: 8192\n model_parameters:\n num_ctx: 4096 # Context window size\n num_predict: -1 # Number of tokens to predict\n repeat_penalty: 1.1 # Penalty for repeating tokens\n top_k: 40 # Limit token selection to top K\n top_p: 0.9 # Cumulative probability cutoff\n```\n\nSee the [config/README.md](config/README.md) for detailed information about YAML configuration.\n\n#### Environment Variables\n\nThe server uses the following environment variables:\n\n- `NEO4J_URI`: URI for the Neo4j database (default: `bolt://localhost:7687`)\n- `NEO4J_USER`: Neo4j username (default: `neo4j`)\n- `NEO4J_PASSWORD`: Neo4j password (default: `demodemo`)\n\n### LLM Configuration\n\nThe server now defaults to using **Ollama** for LLM operations and embeddings. You can configure it using these environment variables:\n\n#### Ollama Configuration (Default)\n- `USE_OLLAMA`: Use Ollama for LLM and embeddings (default: `true`)\n- `OLLAMA_BASE_URL`: Ollama base URL (default: `http://localhost:11434/v1`)\n- `OLLAMA_LLM_MODEL`: Ollama LLM model name (default: `deepseek-r1:7b`)\n- `OLLAMA_EMBEDDING_MODEL`: Ollama embedding model name (default: `nomic-embed-text`)\n- `OLLAMA_EMBEDDING_DIM`: Ollama embedding dimension (default: `768`)\n- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)\n\n**Ollama Model Parameters:** You can now configure Ollama-specific model parameters like `num_ctx`, `top_p`, `repeat_penalty`, etc. using YAML configuration files. This provides fine-grained control over model behavior that wasn't previously available through environment variables alone.\n\n#### OpenAI Configuration (Alternative)\nTo use OpenAI instead of Ollama, set `USE_OLLAMA=false` and configure:\n- `OPENAI_API_KEY`: OpenAI API key (required for LLM operations)\n- `OPENAI_BASE_URL`: Optional base URL for OpenAI API\n- `MODEL_NAME`: OpenAI model name to use for LLM operations (default: `gpt-4.1-mini`)\n- `SMALL_MODEL_NAME`: OpenAI model name to use for smaller LLM operations (default: `gpt-4.1-nano`)\n- `LLM_TEMPERATURE`: Temperature for LLM responses (0.0-2.0)\n- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)\n\n#### Azure OpenAI Configuration (Alternative)\nTo use Azure OpenAI, set `USE_OLLAMA=false` and configure:\n- `AZURE_OPENAI_ENDPOINT`: Azure OpenAI LLM endpoint URL\n- `AZURE_OPENAI_DEPLOYMENT_NAME`: Azure OpenAI LLM deployment name\n- `AZURE_OPENAI_API_VERSION`: Azure OpenAI LLM API version\n- `AZURE_OPENAI_EMBEDDING_API_KEY`: Azure OpenAI Embedding deployment key (if different from `OPENAI_API_KEY`)\n- `AZURE_OPENAI_EMBEDDING_ENDPOINT`: Azure OpenAI Embedding endpoint URL\n- `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`: Azure OpenAI embedding deployment name\n- `AZURE_OPENAI_EMBEDDING_API_VERSION`: Azure OpenAI API version\n- `AZURE_OPENAI_USE_MANAGED_IDENTITY`: Use Azure Managed Identities for authentication\n- `LLM_MAX_TOKENS`: Maximum tokens for LLM responses (default: `8192`)\n\n#### General Configuration\n- `SEMAPHORE_LIMIT`: Episode processing concurrency. See [Concurrency and LLM Provider 429 Rate Limit Errors](#concurrency-and-llm-provider-429-rate-limit-errors)\n- `MCP_SERVER_PORT`: Port for the MCP server when using SSE transport (default: 8020)\n\nYou can set these variables in a `.env` file in the project directory. A sample configuration file (`sample_env.txt`) is provided with all available options and their default values.\n\n## Running the Server\n\nTo run the Graphiti MCP server directly using `uv`:\n\n```bash\nuv run src/graphiti_mcp_server.py\n```\n\nWith options:\n\n```bash\nuv run src/graphiti_mcp_server.py --model gpt-4.1-mini --transport sse\n```\n\nAvailable arguments:\n\n- `--model`: Overrides the `MODEL_NAME` environment variable (only when not using Ollama).\n- `--small-model`: Overrides the `SMALL_MODEL_NAME` environment variable (only when not using Ollama).\n- `--temperature`: Overrides the `LLM_TEMPERATURE` environment variable.\n- `--max-tokens`: Overrides the `LLM_MAX_TOKENS` environment variable.\n- `--transport`: Choose the transport method (sse or stdio, default: sse)\n- `--port`: Port to bind the MCP server to (default: 8020)\n- `--group-id`: Set a namespace for the graph (optional). If not provided, defaults to \"default\".\n- `--destroy-graph`: If set, destroys all Graphiti graphs on startup.\n- `--use-custom-entities`: Enable entity extraction using the predefined ENTITY_TYPES\n\n#### Ollama Configuration Arguments\n- `--use-ollama`: Use Ollama for LLM and embeddings (default: true)\n- `--ollama-base-url`: Ollama base URL (default: http://localhost:11434/v1)\n- `--ollama-llm-model`: Ollama LLM model name (default: deepseek-r1:7b)\n- `--ollama-embedding-model`: Ollama embedding model name (default: nomic-embed-text)\n- `--ollama-embedding-dim`: Ollama embedding dimension (default: 768)\n\n### Ollama Configuration Examples\n\nThe Graphiti MCP server provides flexible configuration options for Ollama models. Here are some common use cases:\n\n#### Basic Configuration Examples\n\n**Use default models:**\n```bash\n# With default .env configuration\nuv run src/graphiti_mcp_server.py\n\n# Or explicitly set in .env file:\n# USE_OLLAMA=true\n# OLLAMA_LLM_MODEL=deepseek-r1:7b\n# OLLAMA_EMBEDDING_MODEL=nomic-embed-text\n```\n\n**Use a different LLM model:**\n```bash\nuv run src/graphiti_mcp_server.py --ollama-llm-model llama3.2:3b\n```\n\n**Use a different embedding model with custom dimension:**\n```bash\nuv run src/graphiti_mcp_server.py --ollama-embedding-model all-minilm-l6-v2 --ollama-embedding-dim 384\n```\n\n**Use custom max tokens for larger responses:**\n```bash\nuv run src/graphiti_mcp_server.py --max-tokens 32768\n```\n\n**Connect to a remote Ollama server:**\n```bash\nuv run src/graphiti_mcp_server.py --ollama-base-url http://remote-server:11434/v1 --ollama-llm-model llama3.2:8b\n```\n\n#### Environment Variable Configuration\n\nYou can also configure Ollama models using environment variables in a `.env` file:\n\n```bash\n# Create or edit .env file\nnano .env\n```\n\nAdd the following variables to your `.env` file:\n\n```env\n# Ollama Configuration\nOLLAMA_LLM_MODEL=mistral:7b\nOLLAMA_EMBEDDING_MODEL=all-minilm-l6-v2\nOLLAMA_EMBEDDING_DIM=384\nLLM_TEMPERATURE=0.1\nLLM_MAX_TOKENS=32768\n```\n\nThen run the server:\n\n```bash\nuv run src/graphiti_mcp_server.py\n```\n\n#### Configuration Priority\n\nThe configuration system follows this priority order (highest to lowest):\n\n1. **CLI arguments** - Override all other settings\n2. **Environment variables** - Provide defaults that can be overridden by CLI\n3. **Default values** - Built-in defaults for all settings\n\n#### Available Ollama Models\n\n**Common LLM Models:**\n- `deepseek-r1:7b` (default) - Good balance of performance and quality\n- `llama3.2:3b` - Fast, smaller model for development\n- `llama3.2:8b` - Higher quality, larger model\n- `mistral:7b` - Excellent performance for many tasks\n- `codellama:7b` - Specialized for code generation\n- `phi3:3.8b` - Microsoft's efficient model\n\n**Common Embedding Models:**\n- `nomic-embed-text` (default) - High-quality embeddings\n- `nomic-embed-text-v2` - Improved version of the default\n- `all-minilm-l6-v2` - Fast, efficient embeddings\n- `all-MiniLM-L6-v2` - Alternative spelling for the same model\n- `text-embedding-ada-002` - OpenAI-compatible embeddings\n\n#### Performance Considerations\n\n- **Smaller models** (3B parameters) are faster but may have lower quality\n- **Larger models** (7B+ parameters) provide better quality but require more resources\n- **Embedding dimensions** affect both performance and storage requirements\n- **Remote Ollama servers** can be used for distributed deployments\n\n### Concurrency and LLM Provider 429 Rate Limit Errors\n\nGraphiti's ingestion pipelines are designed for high concurrency, controlled by the `SEMAPHORE_LIMIT` environment variable.\nBy default, `SEMAPHORE_LIMIT` is set to `10` concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try lowering this value.\n\nIf your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion performance.\n\n### Docker Deployment\n\nThe Graphiti MCP server can be deployed using Docker. The Dockerfile uses `uv` for package management, ensuring\nconsistent dependency installation.\n\n#### Environment Configuration\n\nBefore running the Docker Compose setup, you need to configure the environment variables. You have two options:\n\n1. **Using a .env file** (recommended):\n\n - Copy the provided `.env.example` file to create a `.env` file:\n ```bash\n cp .env.example .env\n ```\n - Edit the `.env` file to set your OpenAI API key and other configuration options:\n ```\n # Required for LLM operations\n OPENAI_API_KEY=your_openai_api_key_here\n MODEL_NAME=gpt-4.1-mini\n # Optional: OPENAI_BASE_URL only needed for non-standard OpenAI endpoints\n # OPENAI_BASE_URL=https://api.openai.com/v1\n ```\n - The Docker Compose setup is configured to use this file if it exists (it's optional)\n\n2. **Using environment variables directly**:\n - You can also set the environment variables when running the Docker Compose command:\n ```bash\n OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up\n ```\n\n#### Neo4j Configuration\n\nThe Docker Compose setup includes a Neo4j container with the following default configuration:\n\n- Username: `neo4j`\n- Password: `demodemo`\n- URI: `bolt://neo4j:7687` (from within the Docker network)\n- Memory settings optimized for development use\n\n#### Running with Docker Compose\n\nA Graphiti MCP container is available at: `zepai/knowledge-graph-mcp`. The latest build of this container is used by the Compose setup below.\n\nStart the services using Docker Compose:\n\n```bash\ndocker compose up\n```\n\nOr if you're using an older version of Docker Compose:\n\n```bash\ndocker-compose up\n```\n\nThis will start both the Neo4j database and the Graphiti MCP server. The Docker setup:\n\n- Uses `uv` for package management and running the server\n- Installs dependencies from the `pyproject.toml` file\n- Connects to the Neo4j container using the environment variables\n- Exposes the server on port 8020 for HTTP-based SSE transport\n- Includes a healthcheck for Neo4j to ensure it's fully operational before starting the MCP server\n\n## Integrating with MCP Clients\n\n### Configuration\n\nTo use the Graphiti MCP server with an MCP-compatible client, configure it to connect to the server:\n\n> [!IMPORTANT]\n> You will need the Python package manager, `uv` installed. Please refer to the [`uv` install instructions](https://docs.astral.sh/uv/getting-started/installation/).\n>\n> Ensure that you set the full path to the `uv` binary and your Graphiti project folder.\n\n#### Using Ollama (Default)\n\n**Basic Ollama configuration:**\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"transport\": \"stdio\",\n \"command\": \"/Users/<user>/.local/bin/uv\",\n \"args\": [\n \"run\",\n \"--isolated\",\n \"--directory\",\n \"/Users/<user>/dev/graphiti-memory\",\n \"--project\",\n \".\",\n \"src/graphiti_mcp_server.py\",\n \"--transport\",\n \"stdio\"\n ],\n \"env\": {\n \"NEO4J_URI\": \"bolt://localhost:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"password\"\n }\n }\n }\n}\n```\n\n**Custom Ollama models via CLI arguments:**\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"transport\": \"stdio\",\n \"command\": \"/Users/<user>/.local/bin/uv\",\n \"args\": [\n \"run\",\n \"--isolated\",\n \"--directory\",\n \"/Users/<user>/dev/graphiti-memory\",\n \"--project\",\n \".\",\n \"src/graphiti_mcp_server.py\",\n \"--transport\",\n \"stdio\",\n \"--ollama-llm-model\",\n \"llama3.2:3b\",\n \"--ollama-embedding-model\",\n \"all-minilm-l6-v2\",\n \"--ollama-embedding-dim\",\n \"384\"\n ],\n \"env\": {\n \"NEO4J_URI\": \"bolt://localhost:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"password\"\n }\n }\n }\n}\n```\n\n**Custom Ollama models via environment variables:**\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"transport\": \"stdio\",\n \"command\": \"/Users/<user>/.local/bin/uv\",\n \"args\": [\n \"run\",\n \"--isolated\",\n \"--directory\",\n \"/Users/<user>/dev/graphiti-memory\",\n \"--project\",\n \".\",\n \"src/graphiti_mcp_server.py\",\n \"--transport\",\n \"stdio\"\n ],\n \"env\": {\n \"NEO4J_URI\": \"bolt://localhost:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"password\",\n \"OLLAMA_LLM_MODEL\": \"mistral:7b\",\n \"OLLAMA_EMBEDDING_MODEL\": \"nomic-embed-text-v2\",\n \"OLLAMA_EMBEDDING_DIM\": \"768\",\n \"LLM_TEMPERATURE\": \"0.1\",\n \"LLM_MAX_TOKENS\": \"32768\"\n }\n }\n }\n}\n```\n\n#### Using OpenAI (Alternative)\n\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"transport\": \"stdio\",\n \"command\": \"/Users/<user>/.local/bin/uv\",\n \"args\": [\n \"run\",\n \"--isolated\",\n \"--directory\",\n \"/Users/<user>/dev/graphiti-memory\",\n \"--project\",\n \".\",\n \"src/graphiti_mcp_server.py\",\n \"--transport\",\n \"stdio\"\n ],\n \"env\": {\n \"NEO4J_URI\": \"bolt://localhost:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"password\",\n \"USE_OLLAMA\": \"false\",\n \"OPENAI_API_KEY\": \"sk-XXXXXXXX\",\n \"MODEL_NAME\": \"gpt-4.1-mini\"\n }\n }\n }\n}\n```\n\nFor SSE transport (HTTP-based), you can use this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"transport\": \"sse\",\n \"url\": \"http://localhost:8020/sse\"\n }\n }\n}\n```\n\n## Available Tools\n\nThe Graphiti MCP server exposes the following tools:\n\n- `add_episode`: Add an episode to the knowledge graph (supports text, JSON, and message formats)\n- `search_nodes`: Search the knowledge graph for relevant node summaries\n- `search_facts`: Search the knowledge graph for relevant facts (edges between entities)\n- `delete_entity_edge`: Delete an entity edge from the knowledge graph\n- `delete_episode`: Delete an episode from the knowledge graph\n- `get_entity_edge`: Get an entity edge by its UUID\n- `get_episodes`: Get the most recent episodes for a specific group\n- `clear_graph`: Clear all data from the knowledge graph and rebuild indices\n- `get_status`: Get the status of the Graphiti MCP server and Neo4j connection\n\n## Working with JSON Data\n\nThe Graphiti MCP server can process structured JSON data through the `add_episode` tool with `source=\"json\"`. This\nallows you to automatically extract entities and relationships from structured data:\n\n```\n\nadd_episode(\nname=\"Customer Profile\",\nepisode_body=\"{\\\"company\\\": {\\\"name\\\": \\\"Acme Technologies\\\"}, \\\"products\\\": [{\\\"id\\\": \\\"P001\\\", \\\"name\\\": \\\"CloudSync\\\"}, {\\\"id\\\": \\\"P002\\\", \\\"name\\\": \\\"DataMiner\\\"}]}\",\nsource=\"json\",\nsource_description=\"CRM data\"\n)\n\n```\n\n## Integrating with the Cursor IDE\n\nTo integrate the Graphiti MCP Server with the Cursor IDE, follow these steps:\n\n1. Run the Graphiti MCP server using the SSE transport:\n\n```bash\npython src/graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>\n```\n\nHint: specify a `group_id` to namespace graph data. If you do not specify a `group_id`, the server will use \"default\" as the group_id.\n\nor\n\n```bash\ndocker compose up\n```\n\n2. Configure Cursor to connect to the Graphiti MCP server.\n\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"url\": \"http://localhost:8020/sse\"\n }\n }\n}\n```\n\n3. Add the Graphiti rules to Cursor's User Rules. See [cursor_rules.md](cursor_rules.md) for details.\n\n4. Kick off an agent session in Cursor.\n\nThe integration enables AI assistants in Cursor to maintain persistent memory through Graphiti's knowledge graph\ncapabilities.\n\n## Integrating with Claude Desktop (Docker MCP Server)\n\nThe Graphiti MCP Server container uses the SSE MCP transport. Claude Desktop does not natively support SSE, so you'll need to use a gateway like `mcp-remote`.\n\n1. **Run the Graphiti MCP server using SSE transport**:\n\n ```bash\n docker compose up\n ```\n\n2. **(Optional) Install `mcp-remote` globally**:\n If you prefer to have `mcp-remote` installed globally, or if you encounter issues with `npx` fetching the package, you can install it globally. Otherwise, `npx` (used in the next step) will handle it for you.\n\n ```bash\n npm install -g mcp-remote\n ```\n\n3. **Configure Claude Desktop**:\n Open your Claude Desktop configuration file (usually `claude_desktop_config.json`) and add or modify the `mcpServers` section as follows:\n\n ```json\n {\n \"mcpServers\": {\n \"graphiti-memory\": {\n // You can choose a different name if you prefer\n \"command\": \"npx\", // Or the full path to mcp-remote if npx is not in your PATH\n \"args\": [\n \"mcp-remote\",\n \"http://localhost:8020/sse\" // Ensure this matches your Graphiti server's SSE endpoint\n ]\n }\n }\n }\n ```\n\n If you already have an `mcpServers` entry, add `graphiti-memory` (or your chosen name) as a new key within it.\n\n4. **Restart Claude Desktop** for the changes to take effect.\n\n## Troubleshooting\n\n### Ollama Configuration Issues\n\n**Server won't start with Ollama:**\n- Ensure Ollama is installed and running: `ollama serve`\n- Check that required models are pulled: `ollama list`\n- Verify Ollama server is accessible: `curl http://localhost:11434/v1/models`\n- Check your `.env` file has `USE_OLLAMA=true` (default)\n\n**Model not found errors:**\n- Pull the required model: `ollama pull <model-name>`\n- Check model name spelling (case-sensitive)\n- Verify model is available in Ollama library\n\n**Embedding dimension mismatch:**\n- Ensure `OLLAMA_EMBEDDING_DIM` matches your embedding model's output dimension\n- Common dimensions: 384 (all-minilm-l6-v2), 768 (nomic-embed-text), 1536 (nomic-embed-text-v2)\n\n**Performance issues:**\n- Try smaller models for faster response times\n- Adjust `SEMAPHORE_LIMIT` for concurrency control\n- Consider using remote Ollama servers for distributed workloads\n\n### General Issues\n\n**Neo4j connection errors:**\n- Verify Neo4j is running and accessible\n- Check connection credentials and URI\n- Ensure Neo4j version is 5.26 or later\n\n**MCP client connection issues:**\n- Verify transport method (stdio vs sse) matches client requirements\n- Check port configuration for SSE transport\n- Ensure firewall allows connections on configured ports\n\n## Requirements\n\n- Python 3.10 or higher\n- Neo4j database (version 5.26 or later required)\n- **Ollama** installed and running (default) OR OpenAI API key (for LLM operations)\n- MCP-compatible client\n\n## Telemetry\n\nThe Graphiti MCP server uses the Graphiti core library, which includes anonymous telemetry collection. When you initialize the Graphiti MCP server, anonymous usage statistics are collected to help improve the framework.\n\n### What's Collected\n\n- Anonymous identifier and system information (OS, Python version)\n- Graphiti version and configuration choices (LLM provider, database backend, embedder type)\n- **No personal data, API keys, or actual graph content is ever collected**\n\n### How to Disable\n\nTo disable telemetry in the MCP server, set the environment variable:\n\n```bash\nexport GRAPHITI_TELEMETRY_ENABLED=false\n```\n\nOr add it to your `.env` file:\n\n```\nGRAPHITI_TELEMETRY_ENABLED=false\n```\n\nFor complete details about what's collected and why, see the [Telemetry section in the main Graphiti README](../README.md#telemetry).\n\n## \ud83d\udce6 Distribution and Publishing\n\nThis project is automatically published to PyPI using GitHub Actions and trusted publishing:\n\n- **PyPI**: https://pypi.org/project/montesmakes.graphiti-memory/\n- **Installation**: `uvx montesmakes.graphiti-memory` or `uv tool install montesmakes.graphiti-memory`\n\n### For Maintainers\n\n- **Release Process**: Use `scripts/prepare-release.sh` to prepare new releases\n- **Publishing Setup**: See [docs/PYPI_SETUP.md](docs/PYPI_SETUP.md) for complete PyPI configuration\n- **Manual Testing**: Use the \"Manual Package Test\" GitHub Action workflow\n\nReleases are automatically published to PyPI when a new GitHub release is created. TestPyPI deployment happens automatically on pushes to the `main` branch.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/mandelbro/graphiti-memory.git\n cd graphiti/mcp_server\n ```\n\n2. **Install dependencies**:\n ```bash\n uv sync --extra dev\n ```\n\n3. **Run tests**:\n ```bash\n uv run pytest\n ```\n\n4. **Format and lint**:\n ```bash\n uv run ruff format\n uv run ruff check\n ```\n\n## License\n\nThis project is licensed under the same license as the parent Graphiti project.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Graphiti MCP Server - Memory service for AI agents built on temporal knowledge graphs",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://github.com/mandelbro/graphiti-memory/blob/main/README.md",
"Homepage": "https://github.com/mandelbro/graphiti-memory",
"Issues": "https://github.com/mandelbro/graphiti-memory/issues",
"Repository": "https://github.com/mandelbro/graphiti-memory.git"
},
"split_keywords": [
"agents",
" ai",
" graphiti",
" knowledge-graph",
" mcp",
" memory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3f7e22feccefeaec6cb9d13e899cc3f7d8ec2a459b8f69d33693e946d5b1bd21",
"md5": "c4abde1e160accdbd4d125c595554676",
"sha256": "688c478c7bf9a2babccfcc656b3ff98aaa950f63dc974f6e3ca4711d75e9cb38"
},
"downloads": -1,
"filename": "montesmakes_graphiti_memory-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4abde1e160accdbd4d125c595554676",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 53563,
"upload_time": "2025-08-13T18:54:08",
"upload_time_iso_8601": "2025-08-13T18:54:08.390027Z",
"url": "https://files.pythonhosted.org/packages/3f/7e/22feccefeaec6cb9d13e899cc3f7d8ec2a459b8f69d33693e946d5b1bd21/montesmakes_graphiti_memory-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "63a3bf03ca1e12fa2e4e1509bc17b19cf271ed2d340b8ed76e0d452d905c9ee0",
"md5": "10cfe73517e27a177fa34d9425b551bb",
"sha256": "ddf9ceaaa3392c90726bee6b990a2d969f79f1870285b07f8ca13d9382287cb5"
},
"downloads": -1,
"filename": "montesmakes_graphiti_memory-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "10cfe73517e27a177fa34d9425b551bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 268250,
"upload_time": "2025-08-13T18:54:09",
"upload_time_iso_8601": "2025-08-13T18:54:09.688066Z",
"url": "https://files.pythonhosted.org/packages/63/a3/bf03ca1e12fa2e4e1509bc17b19cf271ed2d340b8ed76e0d452d905c9ee0/montesmakes_graphiti_memory-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 18:54:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mandelbro",
"github_project": "graphiti-memory",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "montesmakes.graphiti-memory"
}
JSON
