ContextQMD
Back to Graphiti

FalkorDB + Graphiti MCP Server Combined Image

mcp_server/docker/README-falkordb-combined.md

0.29.07.1 KB
Original Source

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:
bash
# Required
OPENAI_API_KEY=your_openai_api_key

# Optional
GRAPHITI_GROUP_ID=main
SEMAPHORE_LIMIT=10
FALKORDB_PASSWORD=
  1. Start the combined service:
bash
cd mcp_server
docker compose -f docker/docker-compose-falkordb-combined.yml up
  1. Access the services:

Using Docker Run

bash
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

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

Build with Specific Graphiti Version

bash
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

bash
# 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

bash
# 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:

bash
# 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:

bash
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:

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

MCP Server Connection Issues

  1. Verify FalkorDB is running:
bash
docker compose -f docker/docker-compose-falkordb-combined.yml exec graphiti-falkordb redis-cli ping
  1. Check MCP server health:
bash
curl http://localhost:8000/health
  1. View all container logs:
bash
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:

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

Production Considerations

  1. Resource Limits: Add resource constraints in docker-compose:
yaml
deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G
  1. Persistent Volumes: Use named volumes or bind mounts for production data
  2. Monitoring: Export logs to external monitoring system
  3. Backups: Regular backups of /var/lib/falkordb/data volume
  4. Security: Set FALKORDB_PASSWORD in production environments

Comparison with Separate Containers

AspectCombined ImageSeparate Containers
Setup ComplexitySimple (one container)Moderate (service dependencies)
Network LatencyLower (localhost)Higher (container network)
Resource UsageLower (shared base)Higher (separate images)
ScalabilityLimitedBetter (scale independently)
DebuggingHarder (multiple processes)Easier (isolated services)
Production UseDevelopment/Single-nodeRecommended

See Also