FalkorDB/FalkorDB-MCPServer

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):
Running with npx
You can run the server directly from the command line using npx:
**Using inline environment variables:**
**Using a .env file:**
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:
> **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.
> **Tip:** Set REDIS_ARGS in .env to pass extra flags to the bundled FalkorDB's redis-server, for example REDIS_ARGS=--appendonly yes. The value is split on whitespace, and the auth flags derived from FALKORDB_PASSWORD are appended after it, so they win on conflict.
>
> Flags that write to disk do not yet survive a docker compose down: the image runs redis-server --dir /var/lib/falkordb/data — appended *after* REDIS_ARGS, so the directory cannot be overridden here — while the falkordb-data volume is mounted at /data. Until #174 moves the mount to the real data directory, RDB and AOF files are written to the container's writable layer.
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:**
2. **Configure environment:**
Edit .env:
3. **Build the project:**
🤖 Claude Desktop Integration
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
Restart Claude Desktop and you'll see the FalkorDB tools available!
📚 Available MCP Tools
Once connected, you can ask Claude to:
🔍 Query Graphs
**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.