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:

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.