graphiti/mcp_server/docker/README-falkordb-combined.md

FalkorDB + Graphiti MCP Server Combined Image

This Docker setup bundles FalkorDB (graph database) and the Graphiti MCP Server into a single container image for simplified deployment.

Overview

The combined image extends the official FalkorDB Docker image to include:

• FalkorDB: Redis-based graph database running on port 6379
• FalkorDB Web UI: Graph visualization interface on port 3000
• Graphiti MCP Server: Knowledge graph API on port 8000

Both services are managed by a startup script that launches FalkorDB as a daemon and the MCP server in the foreground.

Quick Start

Using Docker Compose (Recommended)

1. Create a .env file in the mcp_server directory:

# Required
OPENAI_API_KEY=your_openai_api_key

# Optional
GRAPHITI_GROUP_ID=main
SEMAPHORE_LIMIT=10
FALKORDB_PASSWORD=

2. Start the combined service:

cd mcp_server
docker compose -f docker/docker-compose-falkordb-combined.yml up

3. Access the services:
   • MCP Server: http://localhost:8000/mcp/
   • FalkorDB Web UI: http://localhost:3000
   • FalkorDB (Redis): localhost:6379

Using Docker Run

docker run -d \
  -p 6379:6379 \
  -p 3000:3000 \
  -p 8000:8000 \
  -e OPENAI_API_KEY=your_key \
  -e GRAPHITI_GROUP_ID=main \
  -v falkordb_data:/var/lib/falkordb/data \
  zepai/graphiti-falkordb:latest

Building the Image

Build with Default Version

docker compose -f docker/docker-compose-falkordb-combined.yml build

Build with Specific Graphiti Version

GRAPHITI_CORE_VERSION=0.22.0 docker compose -f docker/docker-compose-falkordb-combined.yml build

Build Arguments

• GRAPHITI_CORE_VERSION: Version of graphiti-core package (default: 0.22.0)
• MCP_SERVER_VERSION: MCP server version tag (default: 1.0.0rc0)
• BUILD_DATE: Build timestamp
• VCS_REF: Git commit hash

Configuration

Environment Variables

All environment variables from the standard MCP server are supported:

Required:

• OPENAI_API_KEY: OpenAI API key for LLM operations

Optional:

• BROWSER: Enable FalkorDB Browser web UI on port 3000 (default: "1", set to "0" to disable)
• GRAPHITI_GROUP_ID: Namespace for graph data (default: "main")
• SEMAPHORE_LIMIT: Concurrency limit for episode processing (default: 10)
• FALKORDB_PASSWORD: Password for FalkorDB (optional)
• FALKORDB_DATABASE: FalkorDB database name (default: "default_db")

Other LLM Providers:

• ANTHROPIC_API_KEY: For Claude models
• GOOGLE_API_KEY: For Gemini models
• GROQ_API_KEY: For Groq models

Volumes

• /var/lib/falkordb/data: Persistent storage for graph data
• /var/log/graphiti: MCP server and FalkorDB Browser logs

Service Management

View Logs

# All logs (both services stdout/stderr)
docker compose -f docker/docker-compose-falkordb-combined.yml logs -f

# Only container logs
docker compose -f docker/docker-compose-falkordb-combined.yml logs -f graphiti-falkordb

Restart Services

# Restart entire container (both services)
docker compose -f docker/docker-compose-falkordb-combined.yml restart

# Check FalkorDB status
docker compose -f docker/docker-compose-falkordb-combined.yml exec graphiti-falkordb redis-cli ping

# Check MCP server status
curl http://localhost:8000/health

Disabling the FalkorDB Browser

To disable the FalkorDB Browser web UI (port 3000), set the BROWSER environment variable to 0:

# Using docker run
docker run -d \
  -p 6379:6379 \
  -p 3000:3000 \
  -p 8000:8000 \
  -e BROWSER=0 \
  -e OPENAI_API_KEY=your_key \
  zepai/graphiti-falkordb:latest

# Using docker-compose
# Add to your .env file:
BROWSER=0

When disabled, only FalkorDB (port 6379) and the MCP server (port 8000) will run.

Health Checks

The container includes a health check that verifies:

1. FalkorDB is responding to ping
2. MCP server health endpoint is accessible

Check health status:

docker compose -f docker/docker-compose-falkordb-combined.yml ps

Architecture

Process Structure

start-services.sh (PID 1)
├── redis-server (FalkorDB daemon)
├── node server.js (FalkorDB Browser - background, if BROWSER=1)
└── uv run main.py (MCP server - foreground)

The startup script launches FalkorDB as a background daemon, waits for it to be ready, optionally starts the FalkorDB Browser (if BROWSER=1), then starts the MCP server in the foreground. When the MCP server stops, the container exits.

Directory Structure

/app/mcp/                    # MCP server application
├── main.py
├── src/
├── config/
│   └── config.yaml          # FalkorDB-specific configuration
└── .graphiti-core-version   # Installed version info

/var/lib/falkordb/data/      # Persistent graph storage
/var/lib/falkordb/browser/   # FalkorDB Browser web UI
/var/log/graphiti/           # MCP server and Browser logs
/start-services.sh           # Startup script

Benefits of Combined Image

1. Simplified Deployment: Single container to manage
2. Reduced Network Latency: Localhost communication between services
3. Easier Development: One command to start entire stack
4. Unified Logging: All logs available via docker logs
5. Resource Efficiency: Shared base image and dependencies

Troubleshooting

FalkorDB Not Starting

Check container logs:

docker compose -f docker/docker-compose-falkordb-combined.yml logs graphiti-falkordb

MCP Server Connection Issues

1. Verify FalkorDB is running:

docker compose -f docker/docker-compose-falkordb-combined.yml exec graphiti-falkordb redis-cli ping

2. Check MCP server health:

curl http://localhost:8000/health

3. View all container logs:

docker compose -f docker/docker-compose-falkordb-combined.yml logs -f

Port Conflicts

If ports 6379, 3000, or 8000 are already in use, modify the port mappings in docker-compose-falkordb-combined.yml:

ports:
  - "16379:6379"  # Use different external port
  - "13000:3000"
  - "18000:8000"

Production Considerations

1. Resource Limits: Add resource constraints in docker-compose:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G

2. Persistent Volumes: Use named volumes or bind mounts for production data
3. Monitoring: Export logs to external monitoring system
4. Backups: Regular backups of /var/lib/falkordb/data volume
5. Security: Set FALKORDB_PASSWORD in production environments

Comparison with Separate Containers

Aspect	Combined Image	Separate Containers
Setup Complexity	Simple (one container)	Moderate (service dependencies)
Network Latency	Lower (localhost)	Higher (container network)
Resource Usage	Lower (shared base)	Higher (separate images)
Scalability	Limited	Better (scale independently)
Debugging	Harder (multiple processes)	Easier (isolated services)
Production Use	Development/Single-node	Recommended

See Also

• Main MCP Server README
• FalkorDB Documentation
• Docker Compose Documentation