Integrate MCP for FalkorDB (#910)

* Integrate MCP for FalkorDB

* fix lint errors

Author: Naseem77

graphiti_core/driver/falkordb_driver.py

@@ -14,6 +14,7 @@
 limitations under the License.
 """
 
+import datetime
 import asyncio
 import logging
 from typing import TYPE_CHECKING, Any
@@ -230,7 +231,29 @@ def clone(self, database: str) -> 'GraphDriver':
         """
         cloned = FalkorDriver(falkor_db=self.client, database=database)
 
-        return cloned
+        return cloned    
+
+    async def health_check(self) -> None:
+        """Check FalkorDB connectivity by running a simple query."""
+        try:
+            await self.execute_query("MATCH (n) RETURN 1 LIMIT 1")
+            return None
+        except Exception as e:
+            print(f"FalkorDB health check failed: {e}")
+            raise
+    
+    @staticmethod
+    def convert_datetimes_to_strings(obj):
+        if isinstance(obj, dict):
+            return {k: FalkorDriver.convert_datetimes_to_strings(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [FalkorDriver.convert_datetimes_to_strings(item) for item in obj]
+        elif isinstance(obj, tuple):
+            return tuple(FalkorDriver.convert_datetimes_to_strings(item) for item in obj)
+        elif isinstance(obj, datetime):
+            return obj.isoformat()
+        else:
+            return obj
 
     def sanitize(self, query: str) -> str:
         """

graphiti_core/driver/neo4j_driver.py

@@ -72,3 +72,12 @@ def delete_all_indexes(self) -> Coroutine:
         return self.client.execute_query(
             'CALL db.indexes() YIELD name DROP INDEX name',
         )
+    
+    async def health_check(self) -> None:
+        """Check Neo4j connectivity by running the driver's verify_connectivity method."""
+        try:
+            await self.client.verify_connectivity()
+            return None
+        except Exception as e:
+            print(f"Neo4j health check failed: {e}")
+            raise

mcp_server/.env.example

@@ -1,11 +1,20 @@
 # Graphiti MCP Server Environment Configuration
 
-# Neo4j Database Configuration
+# Database Configuration
+# Choose between 'neo4j' or 'falkordb'
+DATABASE_TYPE=falkordb
+
 # These settings are used to connect to your Neo4j database
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=demodemo
 
+# These settings are used to connect to your FalkorDB database
+FALKORDB_PORT=6379
+FALKORDB_HOST=localhost
+FALKORDB_USER=
+FALKORDB_PASSWORD=
+
 # OpenAI API Configuration
 # Required for LLM operations
 OPENAI_API_KEY=your_openai_api_key_here

mcp_server/Dockerfile

@@ -30,8 +30,13 @@ RUN groupadd -r app && useradd -r -d /app -g app app
 COPY pyproject.toml uv.lock ./
 
 # Install dependencies first (better layer caching)
+ARG INSTALL_FALKORDB=false
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --no-dev
+    if [ "$INSTALL_FALKORDB" = "true" ]; then \
+        uv sync --frozen --no-dev --extra falkordb; \
+    else \
+        uv sync --frozen --no-dev; \
+    fi
 
 # Copy application code
 COPY graphiti_mcp_server.py ./
@@ -43,7 +48,7 @@ RUN chown -Rv app:app /app
 USER app
 
 # Expose port
-EXPOSE 8000
+EXPOSE $PORT
 
 # Command to run the application
 CMD ["uv", "run", "graphiti_mcp_server.py"]

mcp_server/README.md

@@ -82,11 +82,21 @@ uv sync
 
 ## Configuration
 
-The server uses the following environment variables:
+The server supports both Neo4j and FalkorDB as database backends. Use the `DATABASE_TYPE` environment variable to choose between them.
+
+#### Neo4j Configuration (default)
 
 - `NEO4J_URI`: URI for the Neo4j database (default: `bolt://localhost:7687`)
 - `NEO4J_USER`: Neo4j username (default: `neo4j`)
 - `NEO4J_PASSWORD`: Neo4j password (default: `demodemo`)
+
+#### FalkorDB Configuration
+- `DATABASE_TYPE`: Set to `falkordb`
+- `FALKORDB_HOST`: FalkorDB host (default: `localhost`)
+- `FALKORDB_PORT`: FalkorDB port (default: `6379`)
+- `FALKORDB_USERNAME`: FalkorDB username (optional)
+- `FALKORDB_PASSWORD`: FalkorDB password (optional)
+
 - `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.
@@ -115,7 +125,7 @@ uv run graphiti_mcp_server.py
 With options:
 
 ```bash
-uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse
+uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse --database-type falkordb --port 8001
 ```
 
 Available arguments:
@@ -124,6 +134,7 @@ Available arguments:
 - `--small-model`: Overrides the `SMALL_MODEL_NAME` environment variable.
 - `--temperature`: Overrides the `LLM_TEMPERATURE` environment variable.
 - `--transport`: Choose the transport method (sse or stdio, default: sse)
+- `--database-type`: Choose database backend (neo4j or falkordb, default: neo4j)
 - `--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
@@ -175,11 +186,30 @@ The Docker Compose setup includes a Neo4j container with the following default c
 - URI: `bolt://neo4j:7687` (from within the Docker network)
 - Memory settings optimized for development use
 
+To run only Neo4j with its MCP server:
+```bash
+docker compose up
+```
+- Neo4j MCP server on port 8000
+
+#### FalkorDB Configuration
+
+The Docker Compose setup includes a FalkorDB container with the following default configuration:
+- Host: `falkordb`
+- Port: `6379`
+- No authentication by default
+
+To run only FalkorDB with its MCP server:
+```bash
+docker compose --profile falkordb up
+```
+- FalkorDB MCP server on port 8001
+
 #### 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:
+Start the services using Docker Compose For Neo4j:
 
 ```bash
 docker compose up
@@ -191,13 +221,25 @@ Or if you're using an older version of Docker Compose:
 docker-compose up
 ```
 
-This will start both the Neo4j database and the Graphiti MCP server. The Docker setup:
+For FalkorDB:
+
+```bash
+docker compose --profile falkordb up
+```
+
+Or if you're using an older version of Docker Compose:
+
+```bash
+docker-compose --profile falkordb up
+```
+
+This will start the database(s) and the Graphiti MCP server(s). 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 8000 for HTTP-based SSE transport
-- Includes a healthcheck for Neo4j to ensure it's fully operational before starting the MCP server
+- Connects to the database container using the environment variables
+- Exposes the server on port 8000 (Neo4j) or 8001 (FalkorDB) for HTTP-based SSE transport
+- Includes healthchecks to ensure databases are fully operational before starting the MCP server
 
 ## Integrating with MCP Clients
 

mcp_server/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+    "mcpServers": {
+        "graphiti": {
+            "transport": "sse",
+            "url": "http://localhost:8001/sse"
+        }
+    }
+}

mcp_server/docker-compose.yml

@@ -1,5 +1,6 @@
 services:
   neo4j:
+    profiles: [""]
     image: neo4j:5.26.0
     ports:
       - "7474:7474" # HTTP
@@ -19,7 +20,8 @@ services:
       retries: 5
       start_period: 30s
 
-  graphiti-mcp:
+  graphiti-mcp-neo4j:
+    profiles: [""]
     image: zepai/knowledge-graph-mcp:latest
     build:
       context: .
@@ -31,6 +33,8 @@ services:
       neo4j:
         condition: service_healthy
     environment:
+      - PORT=8000
+      - DATABASE_TYPE=neo4j
       - NEO4J_URI=${NEO4J_URI:-bolt://neo4j:7687}
       - NEO4J_USER=${NEO4J_USER:-neo4j}
       - NEO4J_PASSWORD=${NEO4J_PASSWORD:-demodemo}
@@ -42,6 +46,50 @@ services:
       - "8000:8000" # Expose the MCP server via HTTP for SSE transport
     command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse"]
 
+  falkordb:
+    profiles: ["falkordb"]
+    image: falkordb/falkordb:latest
+    ports:
+      - "6379:6379"
+    command: ["falkordb-server", "--loadmodule", "/FalkorDB/bin/src/falkordb.so"]
+    volumes:
+      - falkordb_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  graphiti-mcp-falkordb:
+    profiles: ["falkordb"]
+    build:
+      args:
+        INSTALL_FALKORDB: "true"
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - path: .env
+        required: false
+    depends_on:
+      falkordb:
+        condition: service_healthy
+    environment:
+      - PORT=8001
+      - DATABASE_TYPE=falkordb
+      - FALKORDB_HOST=falkordb
+      - FALKORDB_PORT=6379
+      - FALKORDB_USER=${FALKORDB_USER:-}
+      - FALKORDB_PASSWORD=${FALKORDB_PASSWORD:-}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - MODEL_NAME=${MODEL_NAME}
+      - PATH=/root/.local/bin:${PATH}
+      - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10}
+    ports:
+      - "8001:8001" # Expose the MCP server via HTTP for SSE transport
+    command: ["uv", "run", "graphiti_mcp_server.py", "--transport", "sse"]
+
 volumes:
   neo4j_data:
   neo4j_logs:
+  falkordb_data: