Model Context Protocol server for FalkorDB graph databases - enables AI assistants to query and manage graph data using natural language
npm install falkordb-mcpserver> š Connect AI models to FalkorDB graph databases through the Model Context Protocol


FalkorDB MCP Server enables AI assistants like Claude to interact with FalkorDB graph databases using natural language. Query your graph data, create relationships, and manage your knowledge graph - all through conversational AI.
This server implements the Model Context Protocol (MCP), allowing AI models to:
- Query graph databases using OpenCypher
- Create and manage nodes and relationships
- Store and retrieve key-value data
- List and explore multiple graphs
- Delete graphs when needed
- Node.js 16+
- FalkorDB instance (running locally or remotely)
- Claude Desktop app (for AI integration)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
``json`
{
"mcpServers": {
"falkordb": {
"command": "npx",
"args": [
"-y",
"falkordb-mcpserver@latest"
],
"env": {
"FALKORDB_HOST": "localhost",
"FALKORDB_PORT": "6379",
"FALKORDB_USERNAME": "",
"FALKORDB_PASSWORD": ""
}
}
}
}
1. Clone and install:
`bash`
git clone https://github.com/SecKatie/falkordb-mcpserver.git
cd falkordb-mcpserver
npm install
2. Configure environment:
`bash`
cp .env.example .env
.env
Edit :`
env`
# Environment Configuration
NODE_ENV=development
# FalkorDB Configuration
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME= # Optional
FALKORDB_PASSWORD= # Optional
# Redis Configuration (for key-value operations)
REDIS_URL=redis://localhost:6379
REDIS_USERNAME= # Optional
REDIS_PASSWORD= # Optional
# Logging Configuration (optional)
ENABLE_FILE_LOGGING=false
3. Build the project:
`bash`
npm run build
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
`json`
{
"mcpServers": {
"falkordb": {
"command": "node",
"args": [
"/absolute/path/to/falkordb-mcpserver/dist/index.js"
]
}
}
}
Restart Claude Desktop and you'll see the FalkorDB tools available!
Once connected, you can ask Claude to:
"Show me all people who know each other"
"Find the shortest path between two nodes"
"What relationships does John have?"
`$3
`
"Create a new person named Alice who knows Bob"
"Add a 'WORKS_AT' relationship between Alice and TechCorp"
"Store my API key in the database"
`$3
`
"List all available graphs"
"Show me the structure of the user_data graph"
"Delete the old_test graph"
`š ļø Development
$3
`bash
Development with hot-reload
npm run devDevelopment with TypeScript execution (faster startup)
npm run dev:tsRun tests
npm testRun tests in watch mode
npm run test:watchRun tests with coverage report
npm run test:coverageLint code
npm run lintLint and auto-fix issues
npm run lint:fixBuild for production
npm run buildStart production server
npm startInspect MCP server with debugging tools
npm run inspectClean build artifacts
npm run cleanFull CI pipeline (test, lint, build)
npm run prepublish
`$3
`
src/
āāā index.ts # MCP server entry point
āāā services/ # Core business logic
ā āāā falkordb.service.ts # FalkorDB operations
ā āāā redis.service.ts # Key-value operations
ā āāā logger.service.ts # Logging and MCP notifications
āāā mcp/ # MCP protocol implementations
ā āāā tools.ts # MCP tool definitions
ā āāā resources.ts # MCP resource definitions
ā āāā prompts.ts # MCP prompt definitions
āāā errors/ # Error handling framework
ā āāā AppError.ts # Custom error classes
ā āāā ErrorHandler.ts # Global error handling
āāā config/ # Configuration management
ā āāā index.ts # Environment configuration
āāā models/ # TypeScript type definitions
ā āāā mcp.types.ts # MCP protocol types
ā āāā mcp-client-config.ts # Configuration models
āāā utils/ # Utility functions
āāā connection-parser.ts # Connection string parsing
`š§ Advanced Configuration
$3
For cloud-hosted FalkorDB instances:
`env
FALKORDB_HOST=your-instance.falkordb.com
FALKORDB_PORT=6379
FALKORDB_USERNAME=your-username
FALKORDB_PASSWORD=your-secure-password
`$3
You can run multiple MCP servers for different FalkorDB instances:
`json
{
"mcpServers": {
"falkordb-dev": {
"command": "node",
"args": ["path/to/server/dist/index.js"],
"env": {
"FALKORDB_HOST": "dev.falkordb.local"
}
},
"falkordb-prod": {
"command": "node",
"args": ["path/to/server/dist/index.js"],
"env": {
"FALKORDB_HOST": "prod.falkordb.com"
}
}
}
}
`š Example Usage
Here's what you can do once connected:
`cypher
// Claude can help you write queries like:
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name, friend.age// Or create complex data structures:
CREATE (alice:Person {name: 'Alice', age: 30})
CREATE (bob:Person {name: 'Bob', age: 25})
CREATE (alice)-[:KNOWS {since: 2020}]->(bob)
// And even analyze your graph:
MATCH path = shortestPath((start:Person)-[*]-(end:Person))
WHERE start.name = 'Alice' AND end.name = 'Charlie'
RETURN path
`š¤ Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
$3
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)This project is licensed under the MIT License - see the LICENSE file for details.
- Built on the Model Context Protocol SDK
- Powered by FalkorDB
- Inspired by the growing MCP ecosystem
- FalkorDB Documentation
- MCP Specification
- OpenCypher Query Language
---
Made with ā¤ļø by the FalkorDB team & Katie Mulliken