FalkorDB FastMCP Server

A Python FastMCP-based Model Context Protocol (MCP) server for FalkorDB graph database. This server enables AI assistants like Claude to interact with FalkorDB graphs through standardized MCP tools and resources.

Features

• Full MCP Compliance: Implements stdio transport following MCP specification
• Python FastMCP Framework: Built on the mature, stable Python FastMCP library
• Cypher Query Execution: Execute Cypher queries against FalkorDB graphs
• Graph Management: List graphs, get metadata, and manage graph databases
• Clean Architecture: Follows patterns from graphiti-org projects
• Type-Safe: Python type hints throughout the codebase

Architecture

This project follows the architecture patterns established in the graphiti-org ecosystem:

src/falkordb_mcp/
 __init__.py          # Package initialization
 config.py            # Environment-based configuration
 service.py           # FalkorDB connection & operations
 server.py            # FastMCP server with tools & resources

See architecture/ for detailed documentation.

Prerequisites

• Python 3.11 or later
• uv (recommended) or pip
• FalkorDB instance (local or remote)

Installation

Using uv (Recommended)

# Clone the repository
cd /home/donbr/graphiti-org/falkordb-fastmcp

# Sync dependencies
uv sync

# Copy environment template
cp .env.example .env
# Edit .env with your FalkorDB credentials

Using pip

pip install -e .

Configuration

Create a .env file with your FalkorDB connection details:

# FalkorDB Connection
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=
FALKORDB_PASSWORD=

# Optional
LOG_LEVEL=INFO

Usage

Development Mode

uv run python main.py

As MCP Server

Run directly:

python main.py

Or via uv:

uv run python main.py

MCP Client Configuration

Claude Code (Global Configuration)

Add to your ~/.claude.json:

{
  "mcpServers": {
    "falkordb": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/donbr/graphiti-org/falkordb-fastmcp",
        "python",
        "main.py"
      ],
      "env": {}
    }
  }
}

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "falkordb": {
      "command": "python",
      "args": ["/absolute/path/to/falkordb-fastmcp/main.py"]
    }
  }
}

Available Tools

execute_query

Execute Cypher queries against a FalkorDB graph.

Parameters:

• graph_name (string, required): Name of the graph
• query (string, required): Cypher query to execute
• params (object, optional): Query parameters

Example:

{
  "graph_name": "social",
  "query": "MATCH (n:Person) RETURN n LIMIT 10"
}

list_graphs

List all available graphs in FalkorDB.

Returns: Array of graph names with count

get_graph_metadata

Get metadata and labels for a specific graph.

Parameters:

• graph_name (string, required): Name of the graph

Available Resources

falkordb://graphs

Provides a list of all available graphs with metadata.

falkordb://status

Server connection status and configuration information.

Development

Project Structure

falkordb-fastmcp/
 src/
    falkordb_mcp/
        __init__.py       # Package initialization
        config.py          # Configuration management
        service.py         # FalkorDB service layer
        server.py          # FastMCP server implementation
 architecture/              # Architecture documentation
    README.md             # Architecture overview
    docs/                 # Detailed documentation
    diagrams/             # Architecture diagrams
 main.py                    # Entry point
 pyproject.toml            # Project configuration
 .env.example              # Environment template
 README.md                 # This file

Running Tests

uv run pytest

Code Quality

# Linting
uv run ruff check .

# Formatting
uv run ruff format .

Comparison with TypeScript Version

This Python implementation improves on the original TypeScript/Express server:

Feature	TypeScript (Original)	Python (FastMCP)
Transport	Custom REST API	Standard MCP (stdio)
Protocol Compliance	Custom endpoints	MCP specification compliant
Framework	Express.js	FastMCP (proven, stable)
Client Compatibility	Limited	Works with any MCP client
Code Complexity	High (routes, middleware)	Low (declarative tools)
Boilerplate	Significant	Minimal
Deployment	Docker required	Simple Python script

Related Projects

• FalkorDB - Graph database
• FastMCP Python - Python MCP framework
• Model Context Protocol - MCP specification
• graphiti-org - Related graph database tools

Architecture Documentation

See the architecture/ directory for comprehensive documentation including:

• Component inventory
• Architecture diagrams
• Data flow documentation
• API reference
• Development guides

License

MIT License - see LICENSE file for details.

Contributing

This project follows the architectural patterns established in the graphiti-org ecosystem. Please review the architecture documentation before contributing.