home / mcp / falkordb mcp server

FalkorDB MCP Server

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

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "falkordb-falkordb-mcpserver": {
      "url": "http://localhost:3000",
      "headers": {
        "MCP_API_KEY": "YOUR_API_KEY",
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "FALKORDB_PASSWORD": "<FALKORDB_PASSWORD>",
        "FALKORDB_USERNAME": "<FALKORDB_USERNAME>"
      }
    }
  }
}

FalkorDB MCP Server enables AI models to query and manage FalkorDB graph databases using natural language. It supports reading from replicas, creating and editing nodes and relationships, exploring multiple graphs, and deleting graphs, all through the Model Context Protocol (MCP). This makes it easy to drive FalkorDB from conversational AI and automated assistants.

How to use

You connect your MCP client to FalkorDB MCP Server using either HTTP transport or standard I/O (stdio) transport. Once connected, you can run read-only queries on replica instances, create and manage graph data, and explore your graphs through natural language powered commands.

How to install

Prerequisites you need before installing: node.js 18 or later, and a FalkorDB instance (local or remote). You may also use Claude Desktop or another MCP client to connect to the server.

Step 1: Install dependencies and prepare the server. You can install and run the MCP server directly via npm and npx.

Step 2: Create the environment configuration file if you want to customize FalkorDB connection and read-only behavior.

Step 3: Start the MCP server in one of the supported modes. See the code blocks for exact commands.

# Quick setup with npm using the npm config example for Claude Desktop
# This sets up the MCP server to run via npx and connects to a local FalkorDB instance
```
```json
{
  "mcpServers": {
    "falkordb": {
      "command": "npx",
      "args": [
        "-y",
        "@falkordb/mcpserver@latest"
      ],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "FALKORDB_USERNAME": "",
        "FALKORDB_PASSWORD": ""
      }
    }
  }
}
```

# Run with npx directly
````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 dotenv file
````bash
npx dotenv-cli -e .env -- npx @falkordb/mcpserver
````

"""
This is useful for quick testing, running the server standalone, or scripting integrations.
"""

Configuration notes

You can enable read-only mode by default to prevent writes, which is helpful when using replica FalkorDB instances or running analytics.

If you plan to run the MCP server alongside FalkorDB in Docker, you can use Docker Compose to start both services together and expose the MCP HTTP endpoint on port 3000.

When using HTTP transport, you may provide an API key for authentication via MCP_API_KEY. This key must be sent in the Authorization header for each request.

Additional notes

You can run multiple MCP servers for different FalkorDB instances by providing separate mcpServers configurations with distinct host, port, and read-only settings.

The MCP server exposes a set of tools to query graphs, manage graph data, and explore the structure of graphs. Use these tools to interact with FalkorDB through natural language prompts.

Troubleshooting and tips

If you encounter authentication errors in HTTP mode, verify that MCP_API_KEY is set and that your client sends the correct Authorization header.

For read-only operations, ensure you are targeting a replica or have readOnly set where appropriate to avoid unintended writes.

Available tools

query_graph

Execute a graph query through MCP, with optional readOnly mode to run in read-only on replicas or when protection against writes is needed.

query_graph_readonly

Always execute graph queries in read-only mode using GRAPH.RO_QUERY for safe, non-modifying access.

create_node

Create a new node with properties in the connected FalkorDB graph.

create_relationship

Create a relationship between two nodes with optional properties.

list_graphs

List all available graphs in the FalkorDB account.

show_structure

Show the schema or structure of a specific graph to understand its nodes and relationships.

delete_graph

Delete a specified graph from FalkorDB when needed.