w3-mcp-server-falkordb 0.1.1

MCP server for graph database operations with FalkorDB

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.

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

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.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:** `[e-mail]`

Output (JSON):

{
  "success": true,
  "data": {
    "columns": ["n"],
    "rows": [
      {"n": {"id": 1, "name": "Alice", "email": "[e-mail]"}},
      {"n": {"id": 2, "name": "Bob", "email": "[e-mail]"}}
    ],
    "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": "[e-mail]"},
    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

• FalkorDB Documentation
• Cypher Query Language
• Model Context Protocol
• FastMCP

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please visit:

• GitHub Issues
• FalkorDB Community