FalkorDB MCP Server

FalkorDB MCP サーバー

FalkorDB 用の Model Context Protocol（MCP）サーバーです。AI モデルがグラフデータベースにクエリを実行し、操作できるようにします。 FalkorDB MCP Server を使うと、Claude などの AI アシスタントが自然言語で FalkorDB のグラフデータベースを操作できます。グラフデータへのクエリ、リレーションの作成、ナレッジグラフの管理を、すべて会話型 AI を通じて行えます。

🎯 これは何ですか？

このサーバーは Model Context Protocol（MCP）を実装しており、AI モデルは次のことができます。

• OpenCypher を使ったグラフデータベースへのクエリ（読み取り専用モードに対応）
• ノードとリレーションの作成と管理
• 複数のグラフの一覧表示と探索
• 必要に応じたグラフの削除
• レプリカインスタンス向け、または誤った書き込みの防止に役立つ読み取り専用クエリ

🚀 クイックスタート

前提条件

• Node.js 18 以降
• FalkorDB インスタンス（ローカルまたはリモートで実行中）
• Claude Desktop アプリ（AI 連携用）

npm から実行する

Claude Desktop の設定（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "falkordb": {
      "command": "npx",
      "args": [
        "-y",
        "@falkordb/mcpserver@latest"
      ],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "FALKORDB_USERNAME": "",
        "FALKORDB_PASSWORD": ""
      }
    }
  }
}

npx で実行する

npx を使うと、コマンドラインからサーバーを直接実行できます。

インライン環境変数を使う場合：

# Run with stdio transport (default)
FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

# Run with HTTP transport
MCP_TRANSPORT=http MCP_PORT=3005 FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

.env ファイルを使う場合：

# Using dotenv-cli to load environment variables from .env
npx dotenv-cli -e .env -- npx @falkordb/mcpserver

次の用途に便利です。

• 手早いテストや開発
• Claude Desktop を使わずにサーバーを単独で実行する
• カスタム連携やスクリプトでの利用

Docker Compose

FalkorDB と MCP サーバーを一緒に実行します：

cp .env.example .env   # create env file; edit to set MCP_API_KEY, FALKORDB_PASSWORD, etc.
docker compose up -d

Note: .env ファイルを省略すると、MCP_API_KEY や FALKORDB_PASSWORD などの変数が空になり、API キー認証が無効になってデータベースのパスワードは使用されません。

Tip: .env で REDIS_ARGS を設定すると、バンドルされた FalkorDB の redis-server に追加のフラグを渡せます。例：REDIS_ARGS=--appendonly yes。値は空白で分割され、FALKORDB_PASSWORD から派生した認証フラグがその後に追加されるため、競合する場合は認証フラグが優先されます。

ディスクに書き込むフラグは、現時点では docker compose down 後も保持されません。イメージは redis-server --dir /var/lib/falkordb/data を実行します。この指定は REDIS_ARGS の後に追加されるため、ここではディレクトリを上書きできません。一方、falkordb-data ボリュームは /data にマウントされます。#174 でマウント先が実際のデータディレクトリに変更されるまでは、RDB ファイルと AOF ファイルはコンテナの書き込み可能レイヤーに保存されます。

これにより、ヘルスチェックと永続ボリュームを備えた FalkorDB と、接続先をあらかじめ設定した MCP サーバーが起動します。

MCP サーバーは HTTP トランスポート モードで実行され、デフォルトでは localhost:8080 で公開されます。クライアントを接続するには、次のように設定します：

• トランスポート： http
• URL： http://localhost:8080
• API キー： MCP_API_KEY 環境変数で設定します（任意）

正確なポートと設定値については、docker-compose.yml を参照してください。

インストール

1. クローンしてインストールします：

   git clone https://github.com/FalkorDB/FalkorDB-MCPServer.git
   cd FalkorDB-MCPServer
   npm install
   

2. 環境を設定します：

   cp .env.example .env
   

   .env を編集します：

   # Environment Configuration
   NODE_ENV=development
   
   # FalkorDB Configuration
   FALKORDB_HOST=localhost
   FALKORDB_PORT=6379
   FALKORDB_USERNAME=    # Optional
   FALKORDB_PASSWORD=    # Optional
   FALKORDB_TLS=false    # Set to 'true' when FalkorDB is behind TLS
   FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode (useful for replicas)
   
   # Logging Configuration (optional)
   ENABLE_FILE_LOGGING=false
   

3. プロジェクトをビルドします：

   npm run build
   

🤖 Claude Desktop との連携

Claude Desktop の設定ファイル（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "falkordb": {
      "command": "node",
      "args": [
        "/absolute/path/to/falkordb-mcpserver/dist/index.js"
      ]
    }
  }
}

Claude Desktop を再起動すると、FalkorDB のツールが利用可能になります！

📚 利用可能な MCP ツール

接続すると、Claude に次の操作を依頼できます：

🔍 グラフをクエリする

"Show me all people who know each other"
"Find the shortest path between two nodes"
"What relationships does John have?"
"Run a read-only query on the replica instance"

Note： query_graph ツールは readOnly パラメーターに対応し、GRAPH.RO_QUERY を使用して読み取り専用モードでクエリを実行できるようになりました。次の用途に最適です：

• レプリカインスタンスでクエリを実行する
• 誤った書き込み操作を防止する
• 本番環境でデータの整合性を確保する

読み取り専用モードで常にクエリを実行する、専用の query_graph_readonly ツールもあります。

パラメーター化クエリ： query_graph ツールと query_graph_readonly ツールは、省略可能な params オブジェクトを受け取ります。これにより、値をクエリテキストとは別に渡し（$name として参照）、Cypher 文字列に連結せずに済みます。これにより、クエリインジェクションのリスクや不正なクエリを回避できます。たとえば、MATCH (p:Person {name: $name}) RETURN p というクエリに対して、params: { "name": "Alice" } を指定します。パラメーター名（ネストされたマップのキーを含む）は、有効な識別子である必要があります。注：FalkorDB では LIMIT／SKIP 句でパラメーターを使用できません。

📝 データを管理する

"Create a new person named Alice who knows Bob"
"Add a 'WORKS_AT' relationship between Alice and TechCorp"

📊 構造を調べる

"List all available graphs"
"Show me the schema of the movies graph"
"What properties do Person nodes usually have in the movies graph?"
"What properties are on ACTED_IN relationships in the movies graph?"
"Delete the old_test graph"

スキーマの検出： FalkorDB はスキーマレスであるため、クエリを実行する前にエージェントが状況を把握するのに役立つツールが 3 つあります。

• get_graph_schema — ノードラベル、リレーションシップの種類、および（任意で）接続トポロジーを返します。各接続は { source, relationship, target } で、source と target はノードラベルの配列（ノードには複数のラベルが付く場合があります）、relationship はリレーションシップの種類です。トポロジーは、上限付きのリレーションシップのサンプル（connectionSampleSize、デフォルトは 10000）から導出され、大規模なグラフでは includeConnections: false を指定して無効にできます。
• get_node_schema / get_relationship_schema — 指定したラベル／種類のノード／リレーションシップを最大 sampleSize 件（デフォルトは 100）サンプリングし、プロパティキーを出現頻度順に並べて返します。また、requestedSampleSize とともに実際の sampledCount も返します。プロパティ名の揺れを見つけるのに役立ちます。

3 つのスキーマツールはいずれも常に読み取り専用（GRAPH.RO_QUERY）で実行されるため、レプリカや読み取り専用のデプロイ環境でも安全に実行できます。

一般的な状況把握のワークフローは、list_graphs → get_graph_schema → get_node_schema / get_relationship_schema → query_graph です。

🛠️ 開発

コマンド

# Development with hot-reload
npm run dev

# Development with TypeScript execution (faster startup)
npm run dev:ts

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Lint code
npm run lint

# Lint and auto-fix issues
npm run lint:fix

# Build for production
npm run build

# Start production server
npm start

# Inspect MCP server with debugging tools
npm run inspect

# Clean build artifacts
npm run clean

# Full CI pipeline (test, lint, build)
npm run prepublish

プロジェクト構成

src/
├── index.ts                   # MCP server entry point
├── services/                  # Core business logic
│   ├── falkordb.service.ts   # FalkorDB 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

🔧 高度な設定

トランスポートモード

サーバーは 2 つのトランスポートモードに対応しています。

stdio（デフォルト）

Claude Desktop などの AI クライアントとの直接連携に使用します。標準入力／出力を介して通信します。

MCP_TRANSPORT=stdio

Streamable HTTP

リモートまたはネットワーク経由でアクセスできるよう、MCP サーバーを HTTP 経由で公開します。MCP Streamable HTTP プロトコルを介した複数の同時セッションに対応しています。

MCP_TRANSPORT=http
MCP_PORT=8080
MCP_API_KEY=your-secret-api-key  # Optional but recommended

HTTP トランスポートを使用する場合、クライアントは initialize メッセージを含む POST リクエストを送信して接続します。サーバーは Mcp-Session-Id ヘッダーを返します。このヘッダーは後続のリクエストに含める必要があります。MCP_API_KEY が設定されている場合、Authorization: Bearer <key> ヘッダーによる API キー認証が適用されます。

HTTP トランスポートのテスト：

1. サーバーを起動します。

   MCP_TRANSPORT=http MCP_PORT=8080 npm start
   

2. MCP Inspector を使って接続します。

   npx @modelcontextprotocol/inspector --transport streamable-http --url http://localhost:8080
   

注： npm run inspect は stdio トランスポートを使用します。HTTP の場合は、上記のようにサーバーとインスペクターを別々に起動してください。

API キー認証：

MCP_API_KEY が設定されている場合、すべての HTTP リクエストに Authorization ヘッダーを含める必要があります。

MCP_TRANSPORT=http MCP_API_KEY=my-secret-key npm start

その場合、クライアントは次の内容を送信する必要があります。

Authorization: Bearer my-secret-key

有効なキーを含まないリクエストには、401 Unauthorized レスポンスが返されます。認証が適用されるのは HTTP モードのみです。stdio モードでは、通信できるのが親プロセスのみであるため、MCP_API_KEY は無視されます。

Docker の使用

Docker Hub のビルド済みイメージを使用する場合：

# Use the latest stable release
docker pull falkordb/mcpserver:latest
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb/mcpserver:latest

# Or use the edge version (latest main branch)
docker pull falkordb/mcpserver:edge

# Or pin to a specific version
docker pull falkordb/mcpserver:1.0.0

ローカルでビルドする場合：

docker build -t falkordb-mcpserver .
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb-mcpserver

または、FalkorDB とともに docker-compose を使用します。

services:
  falkordb:
    image: falkordb/falkordb:latest
    ports:
      - "6379:6379"

  mcp-server:
    image: falkordb/mcpserver:latest  # or use 'build: .' to build locally
    ports:
      - "8080:8080"
    environment:
      - FALKORDB_HOST=falkordb
      - FALKORDB_PORT=6379
      - MCP_TRANSPORT=http
      - MCP_PORT=8080
      - MCP_API_KEY=your-secret-key
    depends_on:
      - falkordb

リモート FalkorDB の使用

クラウドでホストされている FalkorDB インスタンスの場合：

FALKORDB_HOST=your-instance.falkordb.com
FALKORDB_PORT=6379
FALKORDB_USERNAME=your-username
FALKORDB_PASSWORD=your-secure-password

TLS 経由での接続

FalkorDB インスタンスに TLS 経由でしか接続できない場合（FalkorDB Cloud や、AWS NLB または Fly.io などの TLS 終端ロードバランサーの背後にある セルフホスト可能なインスタンスなど）は、FALKORDB_TLS=true を設定してください。サーバーは証明書と ホスト名を検証する TLS 接続を確立し、SNI サーバー名として FALKORDB_HOST を送信します。そのため、ホストには IP アドレスではなく、証明書と一致する DNS 名を指定してください。

FALKORDB_HOST=your-instance.falkordb.com
FALKORDB_PORT=6379
FALKORDB_TLS=true
FALKORDB_USERNAME=your-username
FALKORDB_PASSWORD=your-secure-password

true 以外の値（未設定を含む）では、デフォルトの平文接続が維持されます。

FALKORDB_TLS は、独自の FalkorDB に対してサーバーを実行する場合（npm start、MCP クライアントの設定、または -e FALKORDB_HOST=... -e FALKORDB_TLS=true を指定した docker run）に適用されます。同梱の docker-compose.yml はこの設定を転送しません。Compose は常に、内部ネットワーク経由で MCP サーバーを独自の FalkorDB コンテナに接続します。この接続では平文通信が使われるため、ここで TLS を有効にすると ハンドシェイクに失敗します。

レプリカインスタンスの読み取り専用モード

FalkorDB のレプリカインスタンスに接続する場合や、書き込み操作が実行されないようにしたい場合は、読み取り専用モードをデフォルトで有効にできます。

FALKORDB_DEFAULT_READONLY=true

これにより、すべてのクエリがデフォルトで GRAPH.RO_QUERY を使って実行されます。query_graph ツールで readOnly パラメーターを設定すれば、クエリごとにこの設定を上書きできます。

使用例：

• レプリカインスタンス：レプリケーション構成で、読み取りレプリカへの書き込みを防止します
• 本番環境の安全性：重要なデータが誤って変更されないようにします
• レポート／分析：データが変更されるリスクなしに、ダッシュボード用のクエリを実行します
• マルチテナント環境：特定のユーザーに読み取り専用アクセスを提供します

複数のインスタンスの実行

異なる FalkorDB インスタンス用に複数の MCP サーバーを実行できます。

{
  "mcpServers": {
    "falkordb-dev": {
      "command": "node",
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "dev.falkordb.local",
        "FALKORDB_DEFAULT_READONLY": "false"
      }
    },
    "falkordb-prod-replica": {
      "command": "node", 
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "replica.falkordb.com",
        "FALKORDB_DEFAULT_READONLY": "true"
      }
    }
  }
}

📖 使用例

接続すると、次のような操作ができます。

// 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

🤝 コントリビューション

コントリビューションを歓迎します。詳細については、コントリビューションガイドラインをご覧ください。

開発ワークフロー

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📝 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については、LICENSEファイルをご覧ください。

🙏 謝辞

• Model Context Protocol SDKを基盤に構築されています
• FalkorDBを利用しています
• 成長を続ける MCP エコシステムに着想を得ています

🔗 リソース

• FalkorDB ドキュメント
• MCP 仕様
• OpenCypher クエリ言語

---

FalkorDB チームと Katie Mulliken が ❤️ を込めて制作