Skip to main content
Glama
famtong8-dev

W3 MCP FalkorDB Server

by famtong8-dev

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 -d

Or 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_ENV

3. 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=
EOF

5. 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.py

Opens 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

Simplest way to run the server:

cd /path/to/w3-mcp-server-falkordb

# Run server (stdio mode)
uv run python server.py

Option 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.py

Opens 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-falkordb

Edit ~/.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 execute

  • graph (string, required): Graph name to query

  • params (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 query

  • label (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** - ✓ accessible

Configuration

FALKORDB_URL

Specifies the connection URL for your FalkorDB server (supports http://, https://, and redis:// schemes).

Default: redis://localhost:6379

Set via:

  1. Environment variable:

    export FALKORDB_URL=redis://localhost:6379
    uv run python server.py
  2. .env file:

    FALKORDB_URL=redis://localhost:6379
  3. In 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 queries

Query Flow

  1. User provides Cypher query

  2. Query is sent to FalkorDB

  3. Results are formatted and returned

  4. 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.py

Interactive Testing

For development and debugging, use MCP dev inspector:

uv run mcp dev server.py

Web 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 limit to control result size and response time

  • Parameterized queries: Always use params for dynamic values to avoid injection

  • Graph 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:latest

Query 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 graph parameter in your query

  • Create 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 ping

  • Verify FALKORDB_URL is correct (supports redis://, http://, https://)

  • Try: redis-cli -p 6379 ping

  • Check 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 10

Complex queries

MATCH (p:Person)-[:WORKS_AT]->(c:Company)
RETURN p.name, c.name, count(*) as employee_count
GROUP BY p.name, c.name

Future 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 tools
falkordb_get_nodesA
Read-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"

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_graphsA
Read-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"

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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"

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 3 tool updatesv0.1.1
    • First observedfalkordb_get_nodes
    • First observedfalkordb_list_graphs
    • First observedfalkordb_query

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: listing graphs, retrieving nodes, and executing queries. No overlap.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with the server prefix, using clear verbs (list, get, query).

Tool Count4/5

Three tools is a bit minimal but covers essential operations for a graph database server. Reasonable scope.

Completeness3/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    An 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.
    5
    2
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Neo4j graph database operations, enabling Cypher queries, node/relationship management, and schema discovery.
    1
    BSD 3-Clause
  • A
    license
    A
    quality
    B
    maintenance
    MCP 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.
    8
    MIT