FalkorDB-MCPServer

View on GitHub

FalkorDB-MCPServer is an MCP (Model Context Protocol) server that connects LLMs to FalkorDB

40 stars TypeScriptOthers Updated Sep 3, 2026

falkordbgraphdatabasemcp-server

Documentation

FalkorDB MCP Server

A Model Context Protocol (MCP) server for FalkorDB, allowing AI models to query and interact with graph databases.

FalkorDB MCP Server enables AI assistants like Claude to interact with FalkorDB graph databases using natural language. Query your graph data, create relationships, and manage your knowledge graph - all through conversational AI.

🎯 What is this?

This server implements the Model Context Protocol (MCP), allowing AI models to:

Query graph databases using OpenCypher (with read-only mode support)
Create and manage nodes and relationships
List and explore multiple graphs
Delete graphs when needed
Read-only queries for replica instances or to prevent accidental writes

🚀 Quick Start

Prerequisites

Node.js 18+
FalkorDB instance (running locally or remotely)
Claude Desktop app (for AI integration)

Running from npm

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

json

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

Running with npx

You can run the server directly from the command line using npx:

Using inline environment variables:

bash

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

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

Using a .env file:

bash

# Using dotenv-cli to load environment variables from .env
npx dotenv-cli -e .env -- npx @falkordb/mcpserver

This is useful for:

Quick testing and development
Running the server standalone without Claude Desktop
Custom integrations and scripting

Docker Compose

Run FalkorDB and the MCP server together:

bash

cp .env.example .env   # create env file; edit to set MCP_API_KEY, FALKORDB_PASSWORD, etc.
docker compose up -d

> Note: Skipping the `.env` file leaves variables like `MCP_API_KEY` and `FALKORDB_PASSWORD` empty, which disables API key authentication and uses no database password.

This starts FalkorDB with health checks and persistent volumes, plus the MCP server pre-configured to connect to it.

The MCP server runs in HTTP transport mode and is exposed on `localhost:8080` by default. To connect a client, configure it to use:

Transport: `http`
URL: `http://localhost:8080`
API Key: Set via the `MCP_API_KEY` environment variable (optional)

See `docker-compose.yml` for the exact port and configuration values.

Installation

1. Clone and install:

bash

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

2. Configure environment:

bash

cp .env.example .env

Edit `.env`:

env

# Environment Configuration
   NODE_ENV=development

   # FalkorDB Configuration
   FALKORDB_HOST=localhost
   FALKORDB_PORT=6379
   FALKORDB_USERNAME=    # Optional
   FALKORDB_PASSWORD=    # Optional
   FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode (useful for replicas)

   # Logging Configuration (optional)
   ENABLE_FILE_LOGGING=false

3. Build the project:

bash

npm run build

🤖 Claude Desktop Integration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

json

{
  "mcpServers": {
    "falkordb": {
      "command": "node",
      "args": [
        "/absolute/path/to/falkordb-mcpserver/dist/index.js"
      ]
    }
  }
}

Restart Claude Desktop and you'll see the FalkorDB tools available!

📚 Available MCP Tools

Once connected, you can ask Claude to:

🔍 Query Graphs

text

"Show me all people who know each other"
"Find the shortest path between two nodes"
"What relationships does John have?"
"Run a read-only query on the replica instance"

Note: The `query_graph` tool now supports a `readOnly` parameter to execute queries in read-only mode using `GRAPH.RO_QUERY`. This is ideal for:

Running queries on replica instances
Preventing accidental write operations
Ensuring data integrity in production environments

There's also a dedicated `query_graph_readonly` tool that always executes queries in read-only mode.

Parameterized queries: The `query_graph` and `query_graph_readonly` tools accept an optional `params` object so values can be passed separately from the query text (referenced as `$name`), instead of string-concatenating them into Cypher. This avoids query-injection risks and malformed queries. For example, a query of `MATCH (p:Person {name: $name}) RETURN p` with `params: { "name": "Alice" }`. Parameter names (including nested map keys) must be valid identifiers. Note: FalkorDB does not allow parameters in `LIMIT`/`SKIP` clauses.

📝 Manage Data

text

"Create a new person named Alice who knows Bob"
"Add a 'WORKS_AT' relationship between Alice and TechCorp"

📊 Explore Structure

text

"List all available graphs"
"Show me the schema of the movies graph"
"What properties do Person nodes usually have in the movies graph?"
"What properties are on ACTED_IN relationships in the movies graph?"
"Delete the old_test graph"

Schema discovery: FalkorDB is schemaless, so three tools help an agent orient itself before querying:

`get_graph_schema` — returns node labels, relationship types, and (optionally) the connection topology. Each connection is `{ source, relationship, target }` where `source` and `target` are arrays of node labels (a node may have multiple labels) and `relationship` is the relationship type. Topology is derived from a bounded sample of relationships (`connectionSampleSize`, default `10000`) and can be turned off with `includeConnections: false` on very large graphs.
`get_node_schema` / `get_relationship_schema` — sample up to `sampleSize` (default `100`) nodes/relationships of a given label/type and rank their property keys by frequency, returning the actual `sampledCount` alongside `requestedSampleSize`. Useful for spotting property naming drift.

All three schema tools always execute read-only (`GRAPH.RO_QUERY`), so they are safe to run against replica/read-only deployments.

A typical orientation workflow is: `list_graphs → get_graph_schema → get_node_schema / get_relationship_schema → query_graph`.

🛠️ Development

Commands

bash

# Development with hot-reload
npm run dev

# Development with TypeScript execution (faster startup)
npm run dev:ts

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Lint code
npm run lint

# Lint and auto-fix issues
npm run lint:fix

# Build for production
npm run build

# Start production server
npm start

# Inspect MCP server with debugging tools
npm run inspect

# Clean build artifacts
npm run clean

# Full CI pipeline (test, lint, build)
npm run prepublish

Project Structure

text

src/
├── index.ts                   # MCP server entry point
├── services/                  # Core business logic
│   ├── falkordb.service.ts   # FalkorDB operations
│   └── logger.service.ts     # Logging and MCP notifications
├── mcp/                      # MCP protocol implementations
│   ├── tools.ts             # MCP tool definitions
│   ├── resources.ts         # MCP resource definitions
│   └── prompts.ts           # MCP prompt definitions
├── errors/                   # Error handling framework
│   ├── AppError.ts          # Custom error classes
│   └── ErrorHandler.ts      # Global error handling
├── config/                   # Configuration management
│   └── index.ts             # Environment configuration
├── models/                   # TypeScript type definitions
│   ├── mcp.types.ts         # MCP protocol types
│   └── mcp-client-config.ts # Configuration models
└── utils/                    # Utility functions
    └── connection-parser.ts  # Connection string parsing

🔧 Advanced Configuration

Transport Modes

The server supports two transport modes:

stdio (default)

Used for direct integration with AI clients like Claude Desktop. Communication happens via standard input/output.

env

MCP_TRANSPORT=stdio

Streamable HTTP

Exposes the MCP server over HTTP for remote or networked access. Supports multiple concurrent sessions via the MCP Streamable HTTP protocol.

env

MCP_TRANSPORT=http
MCP_PORT=8080
MCP_API_KEY=your-secret-api-key  # Optional but recommended

When using HTTP transport, clients connect by sending a POST request with an `initialize` message. The server returns an `Mcp-Session-Id` header that must be included in subsequent requests. API key authentication is enforced via the `Authorization: Bearer ` header when `MCP_API_KEY` is set.

Testing HTTP transport:

1. Start the server:

bash

MCP_TRANSPORT=http MCP_PORT=8080 npm start

2. Use the MCP Inspector to connect:

bash

npx @modelcontextprotocol/inspector --transport streamable-http --url http://localhost:8080

> Note: `npm run inspect` uses stdio transport. For HTTP, start the server and inspector separately as shown above.

API Key Authentication:

When `MCP_API_KEY` is set, all HTTP requests must include an `Authorization` header:

bash

MCP_TRANSPORT=http MCP_API_KEY=my-secret-key npm start

Clients must then send:

text

Authorization: Bearer my-secret-key

Requests without a valid key receive a `401 Unauthorized` response. Auth is only enforced in HTTP mode — stdio mode ignores `MCP_API_KEY` since only the parent process can communicate.

Using with Docker

Using pre-built images from Docker Hub:

bash

# Use the latest stable release
docker pull falkordb/mcpserver:latest
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb/mcpserver:latest

# Or use the edge version (latest main branch)
docker pull falkordb/mcpserver:edge

# Or pin to a specific version
docker pull falkordb/mcpserver:1.0.0

Building locally:

bash

docker build -t falkordb-mcpserver .
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb-mcpserver

Or use with `docker-compose` alongside FalkorDB:

yaml

services:
  falkordb:
    image: falkordb/falkordb:latest
    ports:
      - "6379:6379"

  mcp-server:
    image: falkordb/mcpserver:latest  # or use 'build: .' to build locally
    ports:
      - "8080:8080"
    environment:
      - FALKORDB_HOST=falkordb
      - FALKORDB_PORT=6379
      - MCP_TRANSPORT=http
      - MCP_PORT=8080
      - MCP_API_KEY=your-secret-key
    depends_on:
      - falkordb

Using with Remote FalkorDB

For cloud-hosted FalkorDB instances:

env

FALKORDB_HOST=your-instance.falkordb.com
FALKORDB_PORT=6379
FALKORDB_USERNAME=your-username
FALKORDB_PASSWORD=your-secure-password

Read-Only Mode for Replica Instances

If you're connecting to a FalkorDB replica instance or want to ensure no write operations are performed, you can enable read-only mode by default:

env

FALKORDB_DEFAULT_READONLY=true

This will make all queries execute using `GRAPH.RO_QUERY` by default. You can still override this per-query by setting the `readOnly` parameter in the `query_graph` tool.

Use cases:

Replica instances: Prevent writes to read replicas in replication setups
Production safety: Ensure critical data isn't accidentally modified
Reporting/analytics: Run queries for dashboards without risk of data changes
Multi-tenant environments: Provide read-only access to certain users

Running Multiple Instances

You can run multiple MCP servers for different FalkorDB instances:

json

{
  "mcpServers": {
    "falkordb-dev": {
      "command": "node",
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "dev.falkordb.local",
        "FALKORDB_DEFAULT_READONLY": "false"
      }
    },
    "falkordb-prod-replica": {
      "command": "node", 
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "replica.falkordb.com",
        "FALKORDB_DEFAULT_READONLY": "true"
      }
    }
  }
}

📖 Example Usage

Here's what you can do once connected:

cypher

// Claude can help you write queries like:
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name, friend.age

// Or create complex data structures:
CREATE (alice:Person {name: 'Alice', age: 30})
CREATE (bob:Person {name: 'Bob', age: 25})
CREATE (alice)-[:KNOWS {since: 2020}]->(bob)

// And even analyze your graph:
MATCH path = shortestPath((start:Person)-[*]-(end:Person))
WHERE start.name = 'Alice' AND end.name = 'Charlie'
RETURN path