Falkordb

FalkorDB MCP 服务

FalkorDB 的模型上下文协议（MCP）服务，可让 AI 模型查询和操作图数据库。 FalkorDB MCP 服务使 Claude 等 AI 助手能够通过自然语言与 FalkorDB 图数据库交互。查询图数据、创建关系并管理知识图谱——一切都可通过对话式 AI 完成。

🎯 这是什么？

此服务实现了模型上下文协议（MCP），让 AI 模型能够：

• 使用 OpenCypher 查询图数据库（支持只读模式）
• 创建和管理节点及关系
• 列出和探索多个图
• 按需删除图
• 执行只读查询，用于副本实例或防止意外写入

🚀 快速开始

前提条件

• Node.js 18+
• FalkorDB 实例（在本地或远程运行）
• Claude 桌面应用（用于 AI 集成）

从 npm 运行

添加到 Claude 桌面应用配置文件（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 桌面应用，独立运行服务
• 自定义集成和脚本编写

Docker Compose

同时运行 FalkorDB 和 MCP 服务：

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

注意： 跳过 .env 文件会使 MCP_API_KEY 和 FALKORDB_PASSWORD 等变量为空，从而禁用 API 密钥身份验证，且数据库不使用密码。

提示： 在 .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"

注意： 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 没有固定架构，因此有三个工具可以帮助 Agent 在查询前了解情况：

• get_graph_schema — 返回节点标签、关系类型，以及（可选）连接拓扑。每个连接的格式为 { source, relationship, target }，其中 source 和 target 是节点标签的数组（一个节点可以有多个标签），relationship 是关系类型。拓扑根据有界关系样本得出（connectionSampleSize，默认值为 10000）；对于大型图，可通过 includeConnections: false 关闭拓扑。
• get_node_schema / get_relationship_schema — 对指定标签/类型的节点/关系最多抽样 sampleSize 个（默认值为 100），并按出现频率排列其属性键，同时返回实际的 sampledCount 和请求的 requestedSampleSize。适用于发现属性命名不一致的情况。

这三个架构工具始终以只读方式执行（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

🔧 高级配置

传输模式

服务支持两种传输模式：

stdio（默认）

用于与 Claude Desktop 等 AI 客户端直接集成。通过标准输入/输出进行通信。

MCP_TRANSPORT=stdio

Streamable HTTP

通过 HTTP 暴露 MCP 服务，以便远程或通过网络访问。支持通过 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，请按上述说明分别启动服务和 Inspector。

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

或者使用 docker-compose 与 FalkorDB 一同运行：

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，或位于 TLS 终止负载均衡器（如 AWS NLB 或 Fly.io）后面的 可自托管实例），请设置 FALKORDB_TLS=true。服务随后会建立 TLS 连接，并验证证书和 主机名，同时将 FALKORDB_HOST 作为 SNI 服务名称发送，因此主机应为与证书匹配的 DNS 名称，而不是 IP 地址。

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 客户端配置，或通过 docker run 搭配 -e FALKORDB_HOST=... -e FALKORDB_TLS=true）。随附的 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. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📝 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 Model Context Protocol SDK 构建
• 由 FalkorDB 提供支持
• 灵感来自不断发展的 MCP 生态系统

🔗 资源

• FalkorDB 文档
• MCP 规范
• OpenCypher 查询语言

---

由 FalkorDB 团队和 Katie Mulliken 倾情打造 ❤️