# @falkordb/mcpserver 中文文档

规范地址：https://npmcn.com/package/%40falkordb/mcpserver/

版本：1\.3\.0
npm 元数据更新时间：2026-10-05T08:59:01.687Z
中文译文更新时间：2026-11-14T09:26:37.693Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40falkordb/mcpserver
原文对照：https://npmcn.com/package/%40falkordb/mcpserver/?lang=original
项目主页：https://github.com/FalkorDB/FalkorDB-MCPServer#readme
源码仓库：https://github.com/FalkorDB/FalkorDB-MCPServer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：157 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：5 个
- 首次发布：2026-02-23T10:48:10.130Z
- 最新版本发布：2026-07-01T10:03:30.851Z
- 近 30 天下载量：13184（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

FalkorDB 图表数据库的模型上下文协议服务器 - 允许 AI 助手使用自然语言查询和管理图表数据

## 安装

```sh
npm install @falkordb/mcpserver
```

也可以使用：`pnpm add @falkordb/mcpserver`、`yarn add @falkordb/mcpserver`、`bun add @falkordb/mcpserver`

## README

[![Tests](https://img.shields.io/github/actions/workflow/status/falkordb/FalkorDB-MCPServer/node.yml?branch=main)](https://github.com/falkordb/FalkorDB-MCPServer/actions/workflows/node.yml) [![codecov](https://codecov.io/gh/falkordb/FalkorDB-MCPServer/graph/badge.svg?token=pqGhrlbC1F)](https://codecov.io/gh/falkordb/FalkorDB-MCPServer) [![License](https://img.shields.io/github/license/falkordb/FalkorDB-MCPServer.svg)](https://github.com/falkordb/FalkorDB-MCPServer/blob/main/LICENSE) [![Discord](https://img.shields.io/discord/1146782921294884966.svg?style=social&logo=discord)](https://discord.com/invite/99y2Ubh6tg) [![X (formerly Twitter)](https://img.shields.io/badge/follow-%40falkordb-1DA1F2?logo=x&style=social)](https://x.com/falkordb) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)

# FalkordB MCP 服务器

[![Try Free](https://img.shields.io/badge/Try%20Free-FalkorDB%20Cloud-FF8101?labelColor=FDE900&style=for-the-badge&link=https://app.falkordb.cloud)](https://app.falkordb.cloud/)

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

## 这是什么?

此服务器执行 [示范背景协议(MCP)](https://modelcontextprotocol.io/),允许AI模型:

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

## QQ 快速启动

### 先决条件

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

### 从 npm 运行

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

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

### Npx 运行

您可以使用 npx 直接从命令行运行服务器 :

**使用内置环境变量:**

```bash
# 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文件 :**

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

这对于:

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

### 多克编曲

运行 FalkorDB 和 MCP 服务器 :

```bash
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.  **克隆并安装 :**
    
    ```bash
    git clone https://github.com/FalkorDB/FalkorDB-MCPServer.git
    cd FalkorDB-MCPServer
    npm install
    ```
    
2.  **配置环境 :**
    
    ```bash
    cp .env.example .env
    ```
    
    编辑 `.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.  **构建工程 :**
    
    ```bash
    npm run build
    ```
    

## Claude 桌面集成

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

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

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

## 可用的 MCP 工具

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

### QQ 查询图表

```text
"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` 条款.

### 管理数据

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

### 探索结构

```text
"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`。 。 。 .

## 发展

### 图标

```bash
# 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
```

### 项目结构

```text
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客户端整合. 通信是通过标准输入/输出进行的.

```env
MCP_TRANSPORT=stdio
```

#### 可流取的 HTTP

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

```env
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.  启动服务器 :
    
    ```bash
    MCP_TRANSPORT=http MCP_PORT=3000 npm start
    ```
    
2.  使用 MCP 检查器连接 :
    
    ```bash
    npx @modelcontextprotocol/inspector --transport streamable-http --url http://localhost:3000
    ```
    

> **说明:** `npm run inspect` 使用stdio运输. 对于HTTP,如上所示,分别启动服务器和检查器.

**API 密钥认证 :**

何时 `MCP_API_KEY` 设置,所有 HTTP 请求必须包含 `Authorization` 页眉 :

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

然后客户端必须发送 :

```text
Authorization: Bearer my-secret-key
```

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

### 与 Docker 使用

**使用 Docker 枢纽预建的图像 :**

```bash
# 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
```

**本地建筑:**

```bash
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 并列 :

```yaml
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 实例 :

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

### 只读复制模式

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

```env
FALKORDB_DEFAULT_READONLY=true
```

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

**使用大小写 :**

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

### 运行多个实例

您可以为不同的 FalkorDB 实例运行多个 MCP 服务器 :

```json
{
  "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"
      }
    }
  }
}
```

## 示例使用法

这是你连通后可以做的:

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

## 捐款

我们欢迎捐款! 请看我们的 [贡献准则](https://npmcn.com/package/%40falkordb/mcpserver/CONTRIBUTING.md) 详细情况.

### 发展 工作流量

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.  打开拉请求

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40falkordb/mcpserver/LICENSE) 详细文件.

## 承认

-   建造于 [示范背景协议SDK](https://github.com/anthropics/model-context-protocol)
-   电源 [FalkorDB 存档副本](https://www.falkordb.com/)
-   受不断增长的多氯化石蜡生态系统的启发

## 资源

-   [FalkorDB 文档](https://docs.falkordb.com/)
-   [MCP 规格](https://modelcontextprotocol.io/docs)
-   [OpenCypher 查询语言](https://opencypher.org/)

* * *

由FalkorDB团队和Katie Mulliken制作

## 常见问题

### @falkordb/mcpserver 是什么？

FalkorDB 图表数据库的模型上下文协议服务器 - 允许 AI 助手使用自然语言查询和管理图表数据

### 如何安装 @falkordb/mcpserver？

在项目目录运行 npm install @falkordb/mcpserver，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 falkordb-mcp，可以用 npx falkordb-mcp 直接运行。

### @falkordb/mcpserver 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/falkordb\_\_mcpserver 是否存在。

### @falkordb/mcpserver 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @falkordb/mcpserver 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @falkordb/mcpserver 可以商用吗？

@falkordb/mcpserver 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @falkordb/mcpserver 的下载量有多少？

根据 npm 官方下载统计，@falkordb/mcpserver 在 2026/10/14 – 2026/11/12 这 30 天内被下载 13,184 次，日均约 439 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @falkordb/mcpserver 还在维护吗？

最新版本 1\.3\.0 发布于 2026/07/01（4 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/02/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。