graphiti/mcp_server/docker

Docker Deployment for Graphiti MCP Server

This directory contains Docker Compose configurations for running the Graphiti MCP server with graph database backends: FalkorDB (combined image) and Neo4j.

Quick Start

# Default configuration (FalkorDB combined image)
docker-compose up

# Neo4j (separate containers)
docker-compose -f docker-compose-neo4j.yml up

Environment Variables

Create a .env file in this directory with your API keys:

# Required
OPENAI_API_KEY=your-api-key-here

# Optional
GRAPHITI_GROUP_ID=main
SEMAPHORE_LIMIT=10

# Database-specific variables (see database sections below)

Database Configurations

FalkorDB (Combined Image)

File: docker-compose.yml (default)

The default configuration uses a combined Docker image that bundles both FalkorDB and the MCP server together for simplified deployment.

Configuration

# Environment variables
FALKORDB_URI=redis://localhost:6379  # Connection URI (services run in same container)
FALKORDB_PASSWORD=  # Password (default: empty)
FALKORDB_DATABASE=default_db  # Database name (default: default_db)

Accessing Services

• FalkorDB (Redis): redis://localhost:6379
• FalkorDB Web UI: http://localhost:3000
• MCP Server: http://localhost:8000

Data Management

Backup:

docker run --rm -v mcp_server_falkordb_data:/var/lib/falkordb/data -v $(pwd):/backup alpine \
  tar czf /backup/falkordb-backup.tar.gz -C /var/lib/falkordb/data .

Restore:

docker run --rm -v mcp_server_falkordb_data:/var/lib/falkordb/data -v $(pwd):/backup alpine \
  tar xzf /backup/falkordb-backup.tar.gz -C /var/lib/falkordb/data

Clear Data:

docker-compose down
docker volume rm mcp_server_falkordb_data
docker-compose up

Gotchas

• Both FalkorDB and MCP server run in the same container
• FalkorDB uses Redis persistence mechanisms (AOF/RDB)
• Default configuration has no password - add one for production
• Health check only monitors FalkorDB; MCP server startup visible in logs

See README-falkordb-combined.md for detailed information about the combined image.

Neo4j

File: docker-compose-neo4j.yml

Neo4j runs as a separate container service with its own web interface.

Configuration

# Environment variables
NEO4J_URI=bolt://neo4j:7687  # Connection URI (default: bolt://neo4j:7687)
NEO4J_USER=neo4j  # Username (default: neo4j)
NEO4J_PASSWORD=demodemo  # Password (default: demodemo)
NEO4J_DATABASE=neo4j  # Database name (default: neo4j)
USE_PARALLEL_RUNTIME=false  # Enterprise feature (default: false)

Accessing Neo4j

• Web Interface: http://localhost:7474
• Bolt Protocol: bolt://localhost:7687
• MCP Server: http://localhost:8000

Default credentials: neo4j / demodemo

Data Management

Backup:

# Backup both data and logs volumes
docker run --rm -v docker_neo4j_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/neo4j-data-backup.tar.gz -C /data .
docker run --rm -v docker_neo4j_logs:/logs -v $(pwd):/backup alpine \
  tar czf /backup/neo4j-logs-backup.tar.gz -C /logs .

Restore:

# Restore both volumes
docker run --rm -v docker_neo4j_data:/data -v $(pwd):/backup alpine \
  tar xzf /backup/neo4j-data-backup.tar.gz -C /data
docker run --rm -v docker_neo4j_logs:/logs -v $(pwd):/backup alpine \
  tar xzf /backup/neo4j-logs-backup.tar.gz -C /logs

Clear Data:

docker-compose -f docker-compose-neo4j.yml down
docker volume rm docker_neo4j_data docker_neo4j_logs
docker-compose -f docker-compose-neo4j.yml up

Gotchas

• Neo4j takes 30+ seconds to start up - wait for the health check
• The web interface requires authentication even for local access
• Memory heap is configured for 512MB initial, 1GB max
• Page cache is set to 512MB
• Enterprise features like parallel runtime require a license

Switching Between Databases

To switch from FalkorDB to Neo4j (or vice versa):

1. Stop current setup:

   docker-compose down  # Stop FalkorDB combined image
   # or
   docker-compose -f docker-compose-neo4j.yml down  # Stop Neo4j
   

2. Start new database:

   docker-compose up  # Start FalkorDB combined image
   # or
   docker-compose -f docker-compose-neo4j.yml up  # Start Neo4j
   

Note: Data is not automatically migrated between different database types. You'll need to export from one and import to another using the MCP API.

Troubleshooting

Port Conflicts

If port 8000 is already in use:

# Find what's using the port
lsof -i :8000

# Change the port in docker-compose.yml
# Under ports section: "8001:8000"

Container Won't Start

1. Check logs:

   docker-compose logs graphiti-mcp
   

2. Verify .env file exists and contains valid API keys:

   cat .env | grep API_KEY
   

3. Ensure Docker has enough resources allocated

Database Connection Issues

FalkorDB:

• Test Redis connectivity: docker compose exec graphiti-falkordb redis-cli ping
• Check FalkorDB logs: docker compose logs graphiti-falkordb
• Verify both services started: Look for "FalkorDB is ready!" and "Starting MCP server..." in logs

Neo4j:

• Wait for health check to pass (can take 30+ seconds)
• Check Neo4j logs: docker-compose -f docker-compose-neo4j.yml logs neo4j
• Verify credentials match environment variables

FalkorDB:

• Test Redis connectivity: redis-cli -h localhost ping

Data Not Persisting

1. Verify volumes are created:

   docker volume ls | grep docker_
   

2. Check volume mounts in container:

   docker inspect graphiti-mcp | grep -A 5 Mounts
   

3. Ensure proper shutdown:

   docker-compose down  # Not docker-compose down -v (which removes volumes)
   

Performance Issues

FalkorDB:

• Adjust SEMAPHORE_LIMIT environment variable
• Monitor with: docker stats graphiti-falkordb
• Check Redis memory: docker compose exec graphiti-falkordb redis-cli info memory

Neo4j:

• Increase heap memory in docker-compose-neo4j.yml
• Adjust page cache size based on data size
• Check query performance in Neo4j browser

Docker Resources

Volumes

Each database configuration uses named volumes for data persistence:

• FalkorDB (combined): falkordb_data
• Neo4j: neo4j_data, neo4j_logs

Networks

All configurations use the default bridge network. Services communicate using container names as hostnames.

Resource Limits

No resource limits are set by default. To add limits, modify the docker-compose file:

services:
  graphiti-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G

Configuration Files

Each database has a dedicated configuration file in ../config/:

• config-docker-falkordb-combined.yaml - FalkorDB combined image configuration
• config-docker-neo4j.yaml - Neo4j configuration

These files are mounted read-only into the container at /app/mcp/config/config.yaml (for combined image) or /app/config/config.yaml (for Neo4j).