Falkordb Fastmcp
FalkorDB FastMCP based implementation
Ask AI about Falkordb Fastmcp
Powered by Claude · Grounded in docs
I know everything about Falkordb Fastmcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 graphquery(string, required): Cypher query to executeparams(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.
