FalkorDB MCP Server

What is FalkorDB MCP Server about?

A server that implements the Model Context Protocol to allow AI models to query and interact with FalkorDB graph databases. It receives MCP‑formatted requests, forwards them to FalkorDB, and formats the results back to the MCP client.

How to use FalkorDB MCP Server?

1. Clone the repository and install dependencies:

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

2. Configure the server via the .env file (port, FalkorDB host/port, credentials, MCP_API_KEY).
3. Run in development mode with hot‑reloading:

   npm run dev
   

   or build and start for production:

   npm run build
   npm start
   

4. Interact through the exposed HTTP 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 spec.
• Graph query execution – forwards MCP payloads to FalkorDB and returns results in MCP format.
• Health and metadata endpoints – quick status checks and capability discovery.
• Environment‑driven configuration – all settings (port, DB credentials, API key) are managed via .env.
• Docker‑friendly – can be run as a container using the provided MCP configuration snippet.

Use cases of FalkorDB MCP Server

• Enabling generative AI agents to retrieve relational/graph data in real‑time.
• Building chatbot plugins that need to traverse knowledge graphs stored in FalkorDB.
• Integrating graph‑based recommendation engines with large language models.
• Providing a standardized MCP gateway for multiple AI services to share a single FalkorDB instance.

FAQ from the FalkorDB MCP Server

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

Q: How is authentication handled? A: Set FALKORDB_USERNAME and FALKORDB_PASSWORD in the .env file if the FalkorDB instance requires auth. MCP requests are secured with the MCP_API_KEY header.

Q: Can I run the server locally without Docker? A: Yes – simply start it with npm run dev or npm start after cloning and configuring.

Q: What format are MCP responses returned in? A: Responses follow the MCP specification, encapsulating query results, status, and any error information.

Q: Is there a way to list all graphs in the FalkorDB instance? A: Use the GET /api/mcp/graphs endpoint.

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.