FalkorDB Server

The FalkorDB MCP Server exposes a Model Context Protocol (MCP) interface that lets AI models query and manipulate FalkorDB graph data through natural language or structured MCP tools. It supports reading from FalkorDB graphs, creating and managing nodes and relationships, listing available graphs, exploring graph structures, and deleting graphs as needed. The server can run in standard stdio mode for direct Claude Desktop integration or be exposed over HTTP for remote clients. Tools exposed by the MCP server include query_graph for running Cypher-based queries (with an optional read-only mode), query_graph_readonly for guaranteed read-only queries, as well as data-management actions like creating nodes and relationships and exploring or deleting graphs. When using Claude Desktop, you can enable FalkorDB as an MCP server and invoke these tools via natural language prompts such as “Show me all people who know each other” or “Add a WORKS_AT relationship between Alice and TechCorp.” The server also supports read-only operations to prevent unintended writes, and a dedicated read-only tool ensures safety when querying replica instances. To connect, configure transport (stdio by default or http), point the URL to the MCP server, and optionally set an API key for API access control.

Prerequisites:

• Node.js 18+ (NPM comes with Node.js)
• Git
• FalkorDB instance running (local or remote)

1. Clone the repository and install dependencies:

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

2. Configure environment:

cp .env.example .env

Edit .env to set FalkorDB connection details and any optional settings:

# Environment Configuration
NODE_ENV=development

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

# Logging (optional)
ENABLE_FILE_LOGGING=false

3. Build and run:

npm run build
npm start

4. If you want Claude Desktop integration, use the Claude Desktop config guidance provided in the README to register the MCP server via npx and the appropriate environment variables.

Tips and common considerations:

• Transport modes: by default the MCP server uses stdio (direct Claude Desktop integration). You can switch to HTTP transport by setting MCP_TRANSPORT=http and configuring MCP_PORT if needed. The HTTP mode enables remote clients to connect via a URL like http://localhost:3000.
• API key protection: You can enable API key authentication by supplying MCP_API_KEY in the environment and configuring clients accordingly.
• Read-only mode: FALKORDB_DEFAULT_READONLY and the query_graph_readonly tool help ensure safe querying on replica or read-only instances.
• If you encounter connection issues, verify FALKORDB_HOST/PORT and ensure the FalkorDB instance is reachable from the MCP server host. Logs (enabled via ENABLE_FILE_LOGGING) can help diagnose transport and connection problems.
• The server supports both direct queries and data-management actions. Be mindful of permissions and ensure that write operations are allowed only where intended.