FalkordB MCP 服务器

一个用于FalkorDB的模型上下文协议(MCP)服务器,允许AI模型查询并和图表数据库交互. FalkorDB 磁共振 服务器使克洛德等AI助手能够使用自然语言与FalkorDB图数据库互动. 查询你的图表数据,建立关系,管理你的知识图表——全部通过对话AI.

这是什么?

此服务器执行 示范背景协议(MCP),允许AI模型:

• 查询图表数据库 使用 OpenCypher( 有只读模式支持)
• 创建和管理 节点和关系
• 列出和探索 多个图表
• 删除图表 需要时
• 仅读查询 用于复制实例或防止意外写入

QQ 快速启动

先决条件

• 节点.js 18+
• FalkorDB 实例( 本地运行或远程运行)
• Claude桌面应用程序(用于 AI 集成)

从 npm 运行

添加到您的 Claude 桌面配置( E)~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上:

{
  "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

这对于:

• 快速测试和开发
• 在没有克洛德桌面的情况下独立运行服务器
• 自定义集成和脚本

多克编曲

运行 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 密钥认证, 并且没有使用数据库密码 .

这开始FalkorDB进行健康检查并持续发量,加上MCP服务器预先配置以连接到它.

MCP 服务器运行于 HTTP 运输 模式,并打开 localhost:3000 默认。 要连接客户端,请配置它以使用 :

• 运输: http
• URL : http://localhost:3000
• 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_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 桌面集成

添加到您的 Claude 桌面配置( E)~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上:

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

恢复Claude桌面,你会看到FalkordB工具可用!

可用的 MCP 工具

一旦连接,你可以要求克洛德:

QQ 查询图表

"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是无计划的,所以有三个工具帮助一个代理在查询前自我定位:

• 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

可流取的 HTTP

将 MCP 服务器通过 HTTP 显示为远程或网络访问 。 通过MCP流式HTTP协议支持多个并行会话.

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

当使用 HTTP 传输时, 客户端通过发送 POST 请求与一个 initialize 留言。 服务器返回一个 Mcp-Session-Id 必须在后续请求中包含的页眉。 API 密钥认证通过 Authorization: Bearer <key> 当标题 MCP_API_KEY 已经设定.

测试 HTTP 传输 :

1. 启动服务器 :

   MCP_TRANSPORT=http MCP_PORT=3000 npm start
   

2. 使用 MCP 检查器连接 :

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

说明: 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

没有有效密钥的请求收到 a 401 Unauthorized 反应。 Auth 只在 HTTP 模式下执行—— stdio 模式忽略 MCP_API_KEY 因为只有母进程才能沟通.

与 Docker 使用

使用 Docker 枢纽预建的图像 :

# Use the latest stable release
docker pull falkordb/mcpserver:latest
docker run -p 3000:3000 \
  -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 3000:3000 \
  -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:
      - "3000:3000"
    environment:
      - FALKORDB_HOST=falkordb
      - FALKORDB_PORT=6379
      - MCP_TRANSPORT=http
      - MCP_PORT=3000
      - 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

只读复制模式

如果您正在连接一个 FalkorDB 复制实例, 或者想要确保不执行写入操作, 您可以默认启用只读模式 :

FALKORDB_DEFAULT_READONLY=true

这将使用 GRAPH.RO_QUERY 默认。 您仍然可以通过设置 readOnly 参数 query_graph 工具.

使用大小写 :

• 复制实例: 防止在复制设置中读取复制件
• 生产安全:确保关键数据不会意外被修改
• 报告/分析: 运行对仪表板的查询而不会出现数据变化的风险
• 多租户环境: 向某些用户提供只读访问

运行多个实例

您可以为不同的 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. 创建特性分支( E)git checkout -b feature/amazing-feature(中文(简体) )
3. 提交更改( E)git commit -m 'Add amazing feature'(中文(简体) )
4. 推向分行(git push origin feature/amazing-feature(中文(简体) )
5. 打开拉请求

许可证

这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.

承认

• 建造于 示范背景协议SDK
• 电源 FalkorDB 存档副本
• 受不断增长的多氯化石蜡生态系统的启发

资源

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

由FalkorDB团队和Katie Mulliken制作