W3 MCP FalkorDB Server
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@W3 MCP FalkorDB Serverlist all available graphs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
W3 MCP FalkorDB Server
MCP server for graph database operations using FalkorDB - a high-performance graph database via Redis protocol.
Status: ✅ Production Ready
Features
falkordb_query - Execute parameterized Cypher queries with JSON/Markdown/RAW output formats
falkordb_get_nodes - Retrieve and filter nodes by label with configurable limits
falkordb_list_graphs - List all available graphs and their accessibility status
All tools support multiple output formats (JSON, Markdown, RAW) for flexible integration with different clients.
Related MCP server: Neo4j GraphRAG MCP Server
Quick Start
1. Prerequisites Setup
FalkorDB Server
# Using Docker (Recommended)
docker run -p 6379:6379 falkordb/falkordb:latest
# Or using docker-compose
docker-compose up -dOr install locally: FalkorDB Quick Start
2. Clean Setup (Important!)
cd /path/to/w3-mcp-server-falkordb
# Remove old lockfile and venv
rm -rf uv.lock .venv venv
# Unset old environment variable
unset VIRTUAL_ENV3. Install Dependencies
# Install Python dependencies (using uv)
uv sync
# (Optional) Install MCP CLI for dev inspector
uv pip install 'mcp[cli]'4. Configure Environment
Create a .env file or export environment variables:
# FalkorDB (supports redis://, http://, and https:// schemes)
export FALKORDB_URL=redis://localhost:6379
export FALKORDB_PASSWORD= # Optional if using authentication
# Or create .env file
cat > .env << EOF
FALKORDB_URL=redis://localhost:6379
FALKORDB_PASSWORD=
EOF5. Verify Installation
# Check FalkorDB health
curl http://localhost:6379/health 2>/dev/null || echo "FalkorDB running on port 6379"
# Check Python env
uv run python -c "from mcp.server.fastmcp import FastMCP; print('✓ MCP ready')"6. Test with MCP Dev Inspector (Optional)
For interactive testing with a web UI:
# Start MCP dev inspector (requires MCP CLI)
uv run mcp dev server.pyOpens URL like: http://localhost:5173
Features:
✅ Available tools listed with schemas
✅ Test each tool interactively with JSON input
✅ Real-time request/response viewing
✅ Server logs and debugging
Note: If you just want to run the server for Claude Code integration, use uv run python server.py instead.
Usage
Option A: Direct Python (Recommended)
Simplest way to run the server:
cd /path/to/w3-mcp-server-falkordb
# Run server (stdio mode)
uv run python server.pyOption B: MCP Dev Inspector (Development)
Best way to test and debug interactively:
cd /path/to/w3-mcp-server-falkordb
# Start MCP dev inspector (requires MCP CLI)
uv run mcp dev server.pyOpens web UI at http://localhost:5173:
See available tools and schemas
Test each tool with JSON input
View request/response in real-time
See server logs
Option C: Claude Code Integration
Method 1: From PyPI (When Published)
pip install w3-mcp-server-falkordb
# or
uv pip install w3-mcp-server-falkordbEdit ~/.claude/claude_config.json:
{
"mcpServers": {
"falkordb": {
"type": "stdio",
"command": "uv",
"args": ["run", "--with", "w3-mcp-server-falkordb", "w3-mcp-server-falkordb"],
"env": {
"FALKORDB_URL": "redis://localhost:6379",
"FALKORDB_PASSWORD": ""
}
}
}
}Method 2: From Local Source
Edit ~/.claude/claude_config.json:
{
"mcpServers": {
"falkordb": {
"type": "stdio",
"command": "uv",
"args": ["run", "server.py"],
"cwd": "/path/to/w3-mcp-server-falkordb",
"env": {
"FALKORDB_URL": "redis://localhost:6379",
"FALKORDB_PASSWORD": ""
}
}
}
}Then restart Claude Code.
Tools Documentation
Tool Behavior & Safety
Tool | Read-Only | Idempotent | Safe |
falkordb_query | ❌ No (supports writes) | ❌ No | ⚠️ Use params for safety |
falkordb_get_nodes | ✅ Yes (read-only) | ✅ Yes | ✅ Safe |
falkordb_list_graphs | ✅ Yes (read-only) | ✅ Yes | ✅ Safe |
falkordb_query
Execute a Cypher query against FalkorDB with optional parameterization.
Parameters:
query(string, required): Cypher query to executegraph(string, required): Graph name to queryparams(object, optional): Query parameters/variables ($name, $value, etc.)response_format(string): "json", "markdown", or "raw" (default: "json")
Examples:
{
"query": "MATCH (n:Person) RETURN n.name, n.age LIMIT 10",
"graph": "default",
"response_format": "markdown"
}{
"query": "MATCH (n:Person {name: $name}) RETURN n",
"graph": "default",
"params": {"name": "Alice"},
"response_format": "json"
}Output (Markdown):
## Query Results
Graph: `default`
Status: ✓ Success
### Results — 2 row(s)
Columns: `name, age`
**Row 1:**
- **name:** `Alice`
- **age:** `30`
**Row 2:**
- **name:** `Bob`
- **age:** `25`Output (JSON):
{
"success": true,
"data": {
"columns": ["name", "age"],
"rows": [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
],
"count": 2,
"stats": ["took 1.5 ms"]
},
"graph": "default"
}falkordb_get_nodes
Get node information from a graph with optional label filtering.
Parameters:
graph(string, required): Graph name to querylabel(string, optional): Node label to filter by (e.g., "Person", "Company")limit(integer, 1-1000): Max nodes to return (default: 10)response_format(string): "json" or "markdown" (default: "json")
Examples:
{
"graph": "default",
"label": "Person",
"limit": 5,
"response_format": "markdown"
}Output (Markdown):
## Nodes in Graph 'default'
🏷️ Label Filter: `Person`
📊 Limit: 5
✓ Found 5 node(s):
### Node 1
- **id:** `1`
- **name:** `Alice`
- **email:** `alice@example.com`Output (JSON):
{
"success": true,
"data": {
"columns": ["n"],
"rows": [
{"n": {"id": 1, "name": "Alice", "email": "alice@example.com"}},
{"n": {"id": 2, "name": "Bob", "email": "bob@example.com"}}
],
"count": 2,
"stats": []
},
"graph": "default"
}falkordb_list_graphs
List all available graphs in FalkorDB instance.
Parameters:
response_format(string): "json" or "markdown" (default: "json")
Example:
{
"response_format": "json"
}Output (JSON):
{
"url": "redis://localhost:6379",
"status": "connected",
"graphs": [
{"name": "default", "status": "accessible"},
{"name": "myapp", "status": "accessible"}
],
"total_count": 2
}Output (Markdown):
## FalkorDB Graphs
🔗 Server: `redis://localhost:6379`
✓ Status: Connected
📊 Total Graphs: 2
### Available Graphs
1. **default** - ✓ accessible
2. **myapp** - ✓ accessibleConfiguration
FALKORDB_URL
Specifies the connection URL for your FalkorDB server (supports http://, https://, and redis:// schemes).
Default: redis://localhost:6379
Set via:
Environment variable:
export FALKORDB_URL=redis://localhost:6379 uv run python server.py.env file:
FALKORDB_URL=redis://localhost:6379In claude_config.json:
"env": { "FALKORDB_URL": "redis://localhost:6379" }
FALKORDB_PASSWORD
Optional authentication password for FalkorDB.
Default: Empty (no authentication)
Project Structure
w3-mcp-server-falkordb/
├── server.py # MCP server entry point
├── pyproject.toml # Project config
├── .env.example # Environment variables template
├── README.md # This file
├── docker-compose.yml # Docker setup (optional)
└── tests/
└── test_mcp_server.py # Integration tests (optional)How It Works
Architecture
MCP Client (Claude, IDE, etc.)
↓
MCP Server (server.py)
↓
FalkorDB: graph queriesQuery Flow
User provides Cypher query
Query is sent to FalkorDB
Results are formatted and returned
Output is displayed in requested format
Examples
Query for nodes
# Via Claude/MCP interface
falkordb_query(
query="MATCH (n:Person) WHERE n.age > 25 RETURN n.name, n.age",
graph="default",
response_format="markdown"
)Get all Person nodes
# Via Claude/MCP interface
falkordb_get_nodes(
graph="default",
label="Person",
limit=20,
response_format="json"
)Parameterized query (safe)
# Via Claude/MCP interface
falkordb_query(
query="MATCH (n:Person {email: $email}) RETURN n",
graph="default",
params={"email": "user@example.com"},
response_format="json"
)Development
Run tests
pytest tests/Code formatting
black server.py
ruff check server.pyInteractive Testing
For development and debugging, use MCP dev inspector:
uv run mcp dev server.pyWeb UI at http://localhost:5173 provides:
Tool definitions and JSON schemas
Interactive tool testing
Real-time request/response logs
Server output and errors
Performance Tips
Limit parameter: Use
limitto control result size and response timeParameterized queries: Always use
paramsfor dynamic values to avoid injectionGraph selection: Use specific graph names instead of default when possible
Query optimization: Create appropriate indexes in FalkorDB for frequently queried properties
Troubleshooting
FalkorDB connection error
# Check if FalkorDB is running
redis-cli ping
# Or test with curl (if HTTP endpoint available)
curl http://localhost:6379/
# Start FalkorDB with Docker
docker run -p 6379:6379 falkordb/falkordb:latestQuery syntax error
Verify Cypher query syntax
Check FalkorDB documentation for supported syntax
Test queries in FalkorDB console first
Graph not found
Ensure the graph exists in FalkorDB
Verify you are specifying the correct
graphparameter in your queryCreate graph through FalkorDB CLI or external tools if it doesn't exist
Module import errors
# Clean reinstall
rm -rf .venv uv.lock
uv sync
# Verify installation
uv run python -c "from mcp.server.fastmcp import FastMCP; print('✓ MCP installed')"Server hangs on startup
Check if FalkorDB server is running:
redis-cli pingVerify FALKORDB_URL is correct (supports redis://, http://, https://)
Try:
redis-cli -p 6379 pingCheck firewall/network connectivity to the FalkorDB server
Cypher Query Examples
Create nodes
CREATE (p:Person {name: 'Alice', age: 30})
CREATE (c:Company {name: 'Tech Corp'})Create relationships
MATCH (p:Person {name: 'Alice'})
MATCH (c:Company {name: 'Tech Corp'})
CREATE (p)-[:WORKS_AT]->(c)Query with filters
MATCH (p:Person)
WHERE p.age > 25 AND p.age < 35
RETURN p.name, p.age
ORDER BY p.age DESC
LIMIT 10Complex queries
MATCH (p:Person)-[:WORKS_AT]->(c:Company)
RETURN p.name, c.name, count(*) as employee_count
GROUP BY p.name, c.nameFuture Enhancements
Node/Relationship creation tools
Node/Relationship update and delete tools
Batch operation support
Graph creation/deletion utilities
Transaction and rollback support
Query performance metrics and analysis
References
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues and questions, please visit:
Available Tools
3 toolsfalkordb_get_nodesARead-onlyIdempotent
Get node information from a graph.
Retrieves nodes from the specified graph, optionally filtered by label. Returns node IDs, labels, and properties.
Args: params (GetNodesInput): Validated parameters: - graph (str): Graph name (required) - label (str): Optional node label filter - limit (int): Max nodes to return (1-1000, default: 10) - response_format (str): 'json' or 'markdown'
Returns: str: Formatted list of nodes with metadata
Errors: - Graph not found: "Graph 'xyz' does not exist" - Connection error: "Cannot connect to FalkorDB"
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description confirms a read operation and adds error scenarios (graph not found, connection error), providing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Errors sections. It conveys the necessary information without excessive length, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameters, return format, and potential errors. Given the annotations and output schema, it is sufficiently complete for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is effectively high due to descriptions inside GetNodesInput. The description repeats these details but adds error message examples, offering some extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves node information from a graph with optional label filtering. The sibling tools list graphs and run queries, so this tool is well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get nodes from a graph) and provides parameter details like graph name and optional filters. It does not explicitly say when not to use, but the context suggests alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
falkordb_list_graphsARead-onlyIdempotent
List all available graphs in FalkorDB.
Retrieves information about all graphs currently stored in the FalkorDB instance.
Args: params (ListGraphsInput): Validated parameters: - response_format (str): 'markdown' or 'json'
Returns: str: Formatted list of graphs
Errors: - Connection error: "Cannot connect to FalkorDB"
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds a connection error message and confirms it retrieves information, but adds minimal depth beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) with clear sections for Args and Returns. It is front-loaded with the main purpose. Minor redundancy (e.g., 'retrieves information' restates 'list') but no excessive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and existing annotations/output schema, the description provides essential information: purpose, input details, and error handling. It does not detail the output structure, but the presence of an output schema mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists response_format options as 'markdown' or 'json', but the schema enum includes 'raw'. This inaccuracy reduces clarity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all available graphs in FalkorDB' with a specific verb ('list') and resource ('graphs'). It distinguishes from sibling tools (get_nodes, query) by its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing graphs but does not explicitly provide when-to-use or when-not-to-use guidance relative to siblings. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
falkordb_queryB
Execute a Cypher query against FalkorDB.
Sends a Cypher query to FalkorDB and returns results in the specified format. Supports parameterized queries for safety and flexibility.
Args: params (QueryInput): Validated parameters: - query (str): Cypher query to execute - graph (str): Graph name (required) - params (dict): Query parameters/variables - response_format (str): 'json', 'markdown', or 'raw'
Returns: str: Formatted query results
Examples: - Query: "MATCH (n:Person) RETURN n.name LIMIT 10" - Parameterized: "MATCH (n:Person {name: $name}) RETURN n" - With filter: Create index, match patterns, return results
Errors: - Syntax error: "Invalid Cypher syntax" - Graph not found: "Graph 'xyz' does not exist" - Connection error: "Cannot connect to FalkorDB"
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are non-informative (readOnlyHint false, destructiveHint false), so the description must carry behavioral disclosure. It does not clarify that executing arbitrary Cypher queries can modify data, nor does it mention transaction or side-effect behavior. This is a significant gap for a tool that can perform destructive operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (intro, args, returns, examples, errors) and is reasonably concise. Some repetition of parameter details from the schema could be trimmed, but overall it is efficiently organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema (not shown), the description adequately covers input parameters, error types, and usage examples. It lacks details on transaction handling or write behavior, but the core selection and invocation context is sufficiently addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enriches the input schema by listing each parameter (query, graph, params, response_format) with examples and constraints, adding practical context beyond the schema's descriptions. However, some schema properties like 'graph' being required are not explicitly repeated, though implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes Cypher queries against FalkorDB, specifying the main action and resource. However, it does not explicitly differentiate from sibling tools like falkordb_get_nodes or falkordb_list_graphs, which could cause confusion about when to use this general query tool vs specialized ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples and notes on parameterized queries, which imply usage scenarios but do not offer explicit when-to-use or when-not-to-use guidance. There is no mention of alternatives or exclusions, leaving the agent to infer context from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.1- First observed
falkordb_get_nodes - First observed
falkordb_list_graphs - First observed
falkordb_query
TDQS
Scored across 3 tools
Each tool has a distinct purpose: listing graphs, retrieving nodes, and executing queries. No overlap.
All tools follow a consistent snake_case pattern with the server prefix, using clear verbs (list, get, query).
Three tools is a bit minimal but covers essential operations for a graph database server. Reasonable scope.
The tools cover listing, reading, and querying, but lack direct write operations (create, update, delete). However, the query tool can perform these via Cypher.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
The Graph MCP — indexed blockchain data via subgraph GraphQL queries
Repository knowledge graph MCP server for codebase understanding and debugging.
MCP access to the U.S. federal procurement graph: contracts, opportunities, entities, and more.
Related MCP Servers
AlicenseNot gradedqualityAmaintenanceAllows AI models to query and interact with FalkorDB graph databases through the Model Context Protocol (MCP) specification.7641MIT- AlicenseAqualityCmaintenanceAn MCP server that enables LLMs to perform semantic and fulltext searches within Neo4j while executing complex, search-augmented Cypher queries for GraphRAG applications. It provides tools for database schema discovery and supports multi-provider embeddings to facilitate advanced graph traversals.52MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Neo4j graph database operations, enabling Cypher queries, node/relationship management, and schema discovery.1BSD 3-Clause
- AlicenseAqualityBmaintenanceMCP server for Neo4j that provides abstract graph operations for LLMs, enabling safe and consistent interaction with Neo4j databases through tools like search, insert, update, delete, and schema introspection.8MIT