> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Set up and deploy the Graphiti Model Context Protocol server for AI assistants

The Graphiti MCP server provides Model Context Protocol integration, allowing AI assistants like Claude Desktop and Cursor to interact with Graphiti's knowledge graph capabilities through a standardized protocol.

## Overview

The MCP server exposes Graphiti's core functionality through two transport modes:

* **HTTP transport** (default): Accessible at `http://localhost:8000/mcp/` for broad client compatibility
* **stdio transport**: For clients that only support standard input/output

Key capabilities:

* Episode management (add, retrieve, delete)
* Entity and relationship operations
* Semantic and hybrid search
* Group-based data organization
* Graph maintenance operations

## Quick Start

### Docker Deployment (Recommended)

The simplest way to run the MCP server is using Docker with the bundled FalkorDB database:

```bash theme={null}
cd graphiti/mcp_server
docker compose up
```

This starts:

* MCP server on `http://localhost:8000/mcp/`
* FalkorDB on `localhost:6379`
* FalkorDB web UI on `http://localhost:3000`

### Local Development

For development or customization:

```bash theme={null}
# Install dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Run with default settings
uv run main.py

# Run with custom configuration
uv run main.py --config config/custom.yaml
```

## Configuration

The server supports three configuration methods (in order of precedence):

1. Command-line arguments
2. Environment variables
3. `config.yaml` file

### Database Configuration

#### FalkorDB (Default)

FalkorDB is a Redis-based graph database bundled in a single container:

```yaml theme={null}
database:
  provider: "falkordb"
  providers:
    falkordb:
      uri: "redis://localhost:6379"
      password: ""  # Optional
      database: "default_db"
```

#### Neo4j

For production deployments:

```yaml theme={null}
database:
  provider: "neo4j"
  providers:
    neo4j:
      uri: "bolt://localhost:7687"
      username: "neo4j"
      password: "your_password"
      database: "neo4j"
```

Run with Neo4j:

```bash theme={null}
docker compose -f docker/docker-compose-neo4j.yml up
```

### LLM Provider Configuration

The server supports multiple LLM providers:

```yaml theme={null}
llm:
  provider: "openai"  # or "anthropic", "gemini", "groq", "azure_openai"
  model: "gpt-4.1"

embedder:
  provider: "openai"  # or "voyage", "sentence_transformers", "gemini"
  model: "text-embedding-3-small"
```

### Ollama for Local LLM

Run LLMs locally using Ollama:

```yaml theme={null}
llm:
  provider: "openai"
  model: "gpt-oss:120b"  # Your Ollama model
  api_base: "http://localhost:11434/v1"
  api_key: "ollama"  # Dummy key required

embedder:
  provider: "sentence_transformers"
  model: "all-MiniLM-L6-v2"
```

Ensure Ollama is running:

```bash theme={null}
ollama serve
```

### Environment Variables

The `config.yaml` supports environment variable expansion:

```yaml theme={null}
database:
  providers:
    neo4j:
      uri: "${NEO4J_URI:bolt://localhost:7687}"
      username: "${NEO4J_USER:neo4j}"
      password: "${NEO4J_PASSWORD}"

llm:
  api_key: "${OPENAI_API_KEY}"
```

Key environment variables:

* `OPENAI_API_KEY` - OpenAI API key
* `ANTHROPIC_API_KEY` - Anthropic API key
* `GOOGLE_API_KEY` - Google Gemini API key
* `GROQ_API_KEY` - Groq API key
* `AZURE_OPENAI_API_KEY` - Azure OpenAI key
* `SEMAPHORE_LIMIT` - Concurrency control (see [Performance Tuning](/advanced/performance-tuning))

### Command-Line Arguments

```bash theme={null}
uv run main.py \
  --config config.yaml \
  --llm-provider openai \
  --database-provider neo4j \
  --model gpt-4.1 \
  --temperature 0.7 \
  --transport http \
  --group-id my-namespace \
  --destroy-graph  # CAUTION: Destroys all data on startup
```

## Entity Types

The MCP server includes built-in entity types for structured knowledge extraction:

* **Preference**: User preferences, choices, opinions
* **Requirement**: Specific needs or functionality requirements
* **Procedure**: Standard operating procedures
* **Location**: Physical or virtual places
* **Event**: Time-bound activities
* **Organization**: Companies, institutions, groups
* **Document**: Information content (books, articles, videos)
* **Topic**: Subject of conversation (fallback)
* **Object**: Physical items, tools, devices (fallback)

Customize in `config.yaml`:

```yaml theme={null}
graphiti:
  entity_types:
    - name: "Preference"
      description: "User preferences, choices, opinions, or selections"
    - name: "CustomType"
      description: "Your custom entity type"
```

## MCP Client Integration

### Cursor IDE

1. Start the MCP server:
   ```bash theme={null}
   uv run main.py --group-id cursor-workspace
   ```

2. Configure Cursor (`.cursor/mcp.json`):
   ```json theme={null}
   {
     "mcpServers": {
       "graphiti-memory": {
         "url": "http://localhost:8000/mcp/"
       }
     }
   }
   ```

3. Add Graphiti rules to Cursor's User Rules (see `cursor_rules.md`)

### Claude Desktop (via mcp-remote)

Claude Desktop requires the `mcp-remote` gateway for HTTP transport:

1. Start the MCP server:
   ```bash theme={null}
   docker compose up
   ```

2. Install `mcp-remote` (optional, `npx` will fetch it):
   ```bash theme={null}
   npm install -g mcp-remote
   ```

3. Configure Claude Desktop (`claude_desktop_config.json`):
   ```json theme={null}
   {
     "mcpServers": {
       "graphiti-memory": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://localhost:8000/mcp/"
         ]
       }
     }
   }
   ```

4. Restart Claude Desktop

### stdio Transport

For clients supporting only stdio transport:

```json theme={null}
{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/path/to/graphiti/mcp_server",
        "--project",
        ".",
        "main.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX"
      }
    }
  }
}
```

## Available Tools

The MCP server exposes these tools to AI assistants:

### Episode Management

* `add_episode` - Add text, JSON, or message episodes to the graph
* `get_episodes` - Retrieve recent episodes for a group
* `delete_episode` - Remove an episode by UUID

### Entity & Relationship Operations

* `get_entity_edge` - Get an entity edge by UUID
* `delete_entity_edge` - Delete an entity edge
* `search_nodes` - Search for relevant node summaries
* `search_facts` - Search for relevant facts (entity relationships)

### Graph Maintenance

* `clear_graph` - Clear all data and rebuild indices
* `get_status` - Check server and database connection status

## Working with JSON Data

Ingest structured JSON data for entity extraction:

```python theme={null}
add_episode(
    name="Customer Profile",
    episode_body=json.dumps({
        "company": {"name": "Acme Technologies"},
        "products": [
            {"id": "P001", "name": "CloudSync"},
            {"id": "P002", "name": "DataMiner"}
        ]
    }),
    source="json",
    source_description="CRM data"
)
```

## Deployment

### Production Deployment with Neo4j

```yaml theme={null}
# docker-compose.prod.yml
version: '3.8'

services:
  graphiti-mcp:
    image: zepai/knowledge-graph-mcp
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=${NEO4J_PASSWORD}
      - SEMAPHORE_LIMIT=15
    depends_on:
      - neo4j

  neo4j:
    image: neo4j:5.26.0
    ports:
      - "7474:7474"
      - "7687:7687"
    volumes:
      - neo4j_data:/data
    environment:
      - NEO4J_AUTH=neo4j/${NEO4J_PASSWORD}

volumes:
  neo4j_data:
```

### Health Checks

Monitor the MCP server:

```bash theme={null}
curl http://localhost:8000/health
```

Expected response:

```json theme={null}
{
  "status": "healthy",
  "database": "connected",
  "version": "0.22.1"
}
```

## Telemetry

The MCP server uses Graphiti core's telemetry. To disable:

```bash theme={null}
export GRAPHITI_TELEMETRY_ENABLED=false
```

Or in `.env`:

```
GRAPHITI_TELEMETRY_ENABLED=false
```

Telemetry collects:

* Anonymous usage statistics
* System information
* Configuration choices (LLM provider, database type)

**Never collected**: API keys, personal data, graph content, queries

## Troubleshooting

### Connection Issues

**Problem**: MCP client cannot connect to server

**Solutions**:

* Verify server is running: `curl http://localhost:8000/health`
* Check firewall allows port 8000
* For Docker: ensure containers are on same network

### Database Connection Errors

**Problem**: Cannot connect to Neo4j/FalkorDB

**Solutions**:

* Verify database is running
* Check credentials in config or environment
* For Neo4j: ensure Bolt port 7687 is accessible
* For FalkorDB: ensure Redis port 6379 is accessible

### Rate Limit Errors

**Problem**: 429 errors from LLM provider

**Solution**: Lower `SEMAPHORE_LIMIT` (see [Performance Tuning](/advanced/performance-tuning))

## Next Steps

* [Build a REST API service](/advanced/rest-api)
* [Optimize performance](/advanced/performance-tuning)
* [Create custom drivers](/advanced/custom-drivers)
* [Integrate with LangGraph](/advanced/langgraph-agents)