FalkorDB MCP Server

What is FalkorDB MCP Server about?

FalkorDB MCP Server implements a Model Context Protocol (MCP) endpoint for FalkorDB, enabling AI models to query and interact with graph databases through a standardized HTTP API.

How to use FalkorDB MCP Server?

1. Install – clone the repository and run npm install (or use npx -y falkordb-mcpserver for a quick start).
2. Configure – copy .env.example to .env and set environment variables such as PORT, FALKORDB_HOST, FALKORDB_PORT, and MCP_API_KEY.
3. Run –
   • Development: npm run dev (hot‑reloading).
   • Production: npm run build && npm start.
4. Call the API – use the provided endpoints (/api/mcp/metadata, /api/mcp/context, /api/mcp/health, /api/mcp/graphs).

Key features of FalkorDB MCP Server

• MCP compliance – adheres to the Model Context Protocol for seamless AI integration.
• Graph query execution – forwards context requests to FalkorDB and returns structured results.
• Health and metadata endpoints – easy monitoring and discovery of capabilities.
• Environment‑driven configuration – flexible deployment via .env variables.
• Docker ready – example Docker command in the README for containerized usage.

Use cases of FalkorDB MCP Server

• Enabling large language models to retrieve relational graph data for reasoning or grounding.
• Building AI‑augmented knowledge‑graph applications that require real‑time query responses.
• Integrating graph‑based recommendation engines with conversational agents.
• Providing a unified MCP interface for multiple AI services that need graph access.

FAQ from the FalkorDB MCP Server

Q: Which version of Node.js is required? A: Node.js v16 or later.

Q: How do I secure the MCP endpoint? A: Set MCP_API_KEY in the .env file and include the key in request headers.

Q: Can I run the server inside Docker? A: Yes, the README includes a Docker command example; just ensure the .env file is mounted.

Q: What databases does it support? A: It is designed specifically for FalkorDB instances.

Q: How do I add new graph queries? A: Use the /api/mcp/context POST endpoint with a valid MCP payload containing the Cypher/Gremlin query.

FalkorDB MCP Server

A Model Context Protocol (MCP) server for FalkorDB, allowing AI models to query and interact with graph databases.

Overview

This project implements a server that follows the Model Context Protocol (MCP) specification to connect AI models with FalkorDB graph databases. The server translates and routes MCP requests to FalkorDB and formats the responses according to the MCP standard.

Prerequisites

• Node.js (v16 or later)
• npm or yarn
• FalkorDB instance (can be run locally or remotely)

Installation

1. Clone this repository:

   git clone https://github.com/falkordb/falkordb-mcpserver.git
   cd falkordb-mcpserver
   

2. Install dependencies:

   npm install
   

3. Copy the example environment file and configure it:

   cp .env.example .env
   

   Edit .env with your configuration details.

Configuration

Configuration is managed through environment variables in the .env file:

• PORT: Server port (default: 3000)
• NODE_ENV: Environment (development, production)
• FALKORDB_HOST: FalkorDB host (default: localhost)
• FALKORDB_PORT: FalkorDB port (default: 6379)
• FALKORDB_USERNAME: Username for FalkorDB authentication (if required)
• FALKORDB_PASSWORD: Password for FalkorDB authentication (if required)
• MCP_API_KEY: API key for authenticating MCP requests

Usage

Development

Start the development server with hot-reloading:

npm run dev

Production

Build and start the server:

npm run build
npm start

API Endpoints

• GET /api/mcp/metadata: Get metadata about the FalkorDB instance and available capabilities
• POST /api/mcp/context: Execute queries against FalkorDB
• GET /api/mcp/health: Check server health
• GET /api/mcp/graphs: Returns the list of Graphs

MCP Configuration

To use this server with MCP clients, you can add it to your MCP configuration:

{
  "mcpServers": {
    "falkordb": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", "3000:3000",
        "--env-file", ".env",
        "falkordb-mcpserver",
        "falkordb://host.docker.internal:6379"
      ]
    }
  }
}

For client-side configuration:

{
  "defaultServer": "falkordb",
  "servers": {
    "falkordb": {
      "url": "http://localhost:3000/api/mcp",
      "apiKey": "your_api_key_here"
    }
  }
}

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.