Overview

FalkorDB MCP Server implements the Model Context Protocol (MCP) for FalkorDB graph databases, enabling AI models and assistants to query and manipulate graph data as part of their execution context. By exposing graph operations (queries, node/relationship creation, exploration, and administration) through MCP, the server lets LLM-based tools run OpenCypher queries, inspect graph structure, and perform controlled write operations from conversational interfaces.

This server is useful when you want an AI assistant to reason over knowledge graphs, answer graph-structured queries, or automate graph updates while keeping access, transport, and execution semantics consistent with MCP-compatible clients.

Features

MCP-compliant server that speaks the Model Context Protocol for model integrations
Execute OpenCypher against FalkorDB (supports read-only and read-write modes)
Dedicated read-only query mode to target replica instances or prevent accidental writes
Tools to list, inspect, create, and delete graphs, nodes, and relationships
Two transport modes: stdio (default, for embedding in apps like Claude Desktop) and HTTP (for remote clients)
Easily deployable via npx, Docker Compose, or local Node.js setup
Optional API key authentication and environment-driven configuration

Installation / Configuration

Prerequisites:

Node.js 18+
A running FalkorDB instance (local or remote)

Clone and install locally:

git clone https://github.com/FalkorDB/FalkorDB-MCPServer.git
cd FalkorDB-MCPServer
npm install
npm run build

Create a .env from the example and edit:

cp .env.example .env
# then edit .env to set FALKORDB_HOST, FALKORDB_PORT, MCP_API_KEY, etc.

Key environment variables (examples):

Variable	Description	Default
FALKORDB_HOST	FalkorDB host	localhost
FALKORDB_PORT	FalkorDB port	6379
FALKORDB_USERNAME	FalkorDB username (optional)	(empty)
FALKORDB_PASSWORD	FalkorDB password (optional)	(empty)
FALKORDB_DEFAULT_READONLY	Force read-only mode	false
MCP_TRANSPORT	Transport: `stdio` or `http`	stdio
MCP_PORT	HTTP port when using HTTP transport	3000
MCP_API_KEY	Optional API key for HTTP auth	(empty)

Run via npx (quick start):

# stdio transport (default)
FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

# HTTP transport on port 3005
MCP_TRANSPORT=http MCP_PORT=3005 FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

Docker Compose:

cp .env.example .env
# Edit .env to set passwords and MCP_API_KEY
docker compose up -d

The included compose file starts FalkorDB and the MCP server together; by default the server uses HTTP transport exposed on localhost:3000.

Claude Desktop integration (stdio): Add a server entry to Claude Desktop config (macOS path shown):

{
  "mcpServers": {
    "falkordb": {
      "command": "npx",
      "args": ["-y", "@falkordb/mcpserver@latest"],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379"
      }
    }
  }
}

Or point Claude to a local build by invoking node with the built index.js file.

Available Tools / API surface

When connected via MCP, the server exposes tools that models can call (examples):

query_graph: Run an OpenCypher query against a specified graph (supports readOnly flag)
query_graph_readonly: Same as query_graph but always enforces read-only execution
create_node / create_relationship: Create nodes or relationships with properties
list_graphs: Return available graphs and basic metadata
get_graph_schema: Inspect labels, relationship types, and indexes
delete_graph: Remove an entire graph (requires authorization)

Example OpenCypher query:

MATCH (p:Person)-[r:KNOWS]->(q:Person)
WHERE p.name = "Alice"
RETURN q.name AS friend, r.since AS since

Use Cases

Conversational knowledge-base exploration: Let a model answer questions by executing OpenCypher queries against a knowledge graph.
Assisted graph maintenance: Allow an agent to create or update nodes and relationships based on natural-language commands, while audit-logging writes.
Read-only reporting: Run analytics or read-only queries on replica instances to avoid writing to primary data.
Application integrations: Wire an LLM-powered assistant into admin dashboards that perform graph discovery and structural analysis.

Concrete example: “Find shortest path between two entities”

The model invokes query_graph with a parameterized OpenCypher shortest-path query, receives the path nodes/relationships, and returns a human-readable explanation.

Concrete example: “Add employee record”

The model calls create_node for the Person node and create_relationship to connect it to an Organization node, using values parsed from user input.

Development & Contributing

Tests are run via GitHub Actions in the upstream repository.
Contributions: fork, implement, open PRs; follow the repository’s linting and testing guidelines.
For local debugging, run with NODE_ENV=development and enable file logging via env vars if needed.

Security & Operational Notes

Use MCP_API_KEY to protect the HTTP transport in production.
For read-only scenarios, set FALKORDB_DEFAULT_READONLY=true or use the read-only tools to protect data integrity.
Ensure network and FalkorDB credentials are managed securely (secrets manager or environment injection).

Links

Repository: https://github.com/FalkorDB/FalkorDB-MCPServer
Model Context Protocol: https://modelcontextprotocol.io

FalkorDB MCP Server for AI Model Graph Queries