HelloWorld
登录
N

Neo4j知识图谱

启用以图形数据库格式存储和检索知识的功能，允许用户通过自然语言在由 Neo4j 驱动的知识图谱中创建、更新、搜索和删除实体与关系。

knowledge-and-memorydatabases

3.2k 查看 · 2026-07-07 更新

简介

启用以图形数据库格式存储和检索知识的功能，允许用户通过自然语言在由 Neo4j 驱动的知识图谱中创建、更新、搜索和删除实体与关系。

简介

启用以图形数据库格式存储和检索知识的功能，允许用户通过自然语言在由 Neo4j 驱动的知识图谱中创建、更新、搜索和删除实体与关系。

Neo4j MCP 服务器

这是一个使用 Neo4j 作为后端存储的知识图谱管理的内存控制协议 (MCP) 服务器实现。它提供了一个基于标准输入输出接口，用于以图数据库格式存储和检索知识。

前提条件

  • Python 3.8+
  • Neo4j 数据库（本地或远程）
  • Poetry（Python 包管理器）
  • Docker 和 Docker Compose（用于运行 Neo4j）
  • Go Task（可选，用于任务自动化）

安装

  1. 克隆仓库：
git clone <repository-url>
cd neo4j_mcp_server
  1. 如果你还没有安装 Poetry，请先安装：
curl -sSL https://install.python-poetry.org | python3 -
  1. 安装依赖项：
poetry install

配置

Claude 桌面配置

对于在 Ubuntu 上运行 Claude 桌面的用户，可以通过在以下位置添加 MCP 服务器到你的 Claude 桌面配置文件来配置 MCP 服务器：

~/.config/Claude/claude_desktop_config.json

在配置之前，你需要构建独立的可执行文件：

task build

这将在 dist/neo4j_mcp_server 创建一个二进制文件。确保在你的配置中更新路径指向这个构建的可执行文件。

示例配置文件在 example_mcp_config.json 中提供。你可以复制并修改这个文件：

cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json

然后编辑配置文件中的 command 路径，使其指向你构建的可执行文件：

{
  "mcpServers": [
    {
      "name": "neo4j-knowledge-graph",
      "command": ["/path/to/your/dist/neo4j_mcp_server"],
      ...
    }
  ]
}

配置包括：

  • 服务器名称和描述
  • 启动服务器的命令（指向构建的可执行文件的路径）
  • 可用工具及其参数
  • 必需字段和数据类型

运行服务器

使用 Task（推荐）

如果你已经安装了 Go Task，可以使用提供的 Taskfile 来管理服务器：

# Show available tasks
task

# Start everything (Docker + Server)
task run

# Start development environment (Docker + Server + Test)
task dev

# Stop all services
task down

直接使用 Docker Compose

  1. 启动 Neo4j 容器：
docker-compose up -d
  1. 等待 Neo4j 准备就绪（容器将在 docker ps 中显示为 "healthy"）

直接运行 MCP 服务器

使用以下命令启动服务器：

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

服务器将以标准输入输出模式启动，准备好接收 MCP 协议消息。

可用工具

1. 创建实体

在知识图谱中创建新实体。每个实体必须有类型和属性。如果未明确提供 ID，则会从 name 属性自动设置 ID。

参数：

  • entities: 实体对象列表，每个包含：
    • type: 字符串 - 实体类型（例如，Person, Organization）
    • properties: 对象 - 实体属性的键值对（必须包含 'id' 或 'name'）

示例输入：

{
    "entities": [{
        "type": "Person",
        "properties": {
            "name": "John Doe",
            "occupation": "Developer",
            "age": 30
        }
    }]
}

2. 创建关系

在现有实体之间创建关系。所有引用的实体在创建关系之前必须存在。

参数：

  • relations: 关系对象列表，每个包含：
    • type: 字符串 - 关系类型（例如，KNOWS, WORKS_FOR）
    • from: 字符串 - 源实体的 ID
    • to: 字符串 - 目标实体的 ID

示例输入：

{
    "relations": [{
        "type": "KNOWS",
        "from": "john_doe",
        "to": "jane_smith"
    }]
}

3. 搜索实体

搜索知识图谱中的实体。 （原文似乎在此处中断，没有提供关于“搜索实体”的更多详细信息或示例。）

在知识图谱中搜索实体，具有强大的文本匹配和过滤功能。可以用于按文本搜索、按类型列出实体、查找具有特定属性的实体，或这些过滤器的任意组合。

参数：

  • search_term: 字符串（可选）- 在实体属性中搜索的文本。如果未提供，则根据其他过滤条件返回实体。
  • entity_type: 字符串（可选）- 按实体类型（例如，人、组织）过滤结果。如果单独提供，将返回该类型的全部实体。
  • properties: 字符串列表（可选）- 用于过滤的属性名称列表：
    • 结合 search_term 使用：在这些属性中搜索指定的术语
    • 不结合 search_term 使用：返回定义了这些属性中的任何一个的实体
  • include_relationships: 布尔值（可选，默认为 false）- 是否包含连接的实体及其关系
  • fuzzy_match: 布尔值（可选，默认为 true）- 当提供了 search_term 时，是否使用不区分大小写的部分匹配

示例输入：

// Search by text with type filter
{
    "search_term": "John",
    "entity_type": "Person",
    "properties": ["name", "occupation"],
    "include_relationships": true
}

// List all entities of a type
{
    "entity_type": "Person"
}

// Find entities with specific properties
{
    "properties": ["email", "phone"],
    "entity_type": "Contact"
}

// Combine filters
{
    "entity_type": "Person",
    "properties": ["email"],
    "search_term": "example.com",
    "fuzzy_match": true
}

// Return all entities (no filters)
{}

返回：

{
    "results": [
        {
            "id": "john_doe",
            "type": ["Entity", "Person"],
            "properties": {
                "name": "John Doe",
                "email": "john@example.com"
            },
            "relationships": [  // Only included if include_relationships is true
                {
                    "type": "WORKS_AT",
                    "direction": "outgoing",
                    "node": {
                        "id": "tech_corp",
                        "type": "Company",
                        "properties": {
                            "name": "Tech Corp"
                        }
                    }
                }
            ]
        }
    ]
}

注意事项：

  • 当没有提供任何过滤条件时，返回所有实体
  • 实体类型过滤是精确匹配（非模糊）
  • 属性存在性检查通过 IS NOT NULL 完成
  • 当 fuzzy_match 为真时，文本搜索支持不区分大小写的部分匹配
  • 空结果以空数组形式返回，而不是错误
  • 性能考虑：
    • 按类型过滤比文本搜索更高效
    • 属性存在性检查经过优化
    • 考虑使用特定属性而非搜索所有属性
    • 大量的结果集可能在未来版本中进行分页

4. 更新实体

更新知识图谱中的现有实体。支持添加/移除属性和标签。

参数：

  • updates: 更新对象列表，每个对象包含：
    • id: 字符串（必填）- 要更新的实体ID
    • properties: 对象（可选）- 要更新或添加的属性
    • remove_properties: 字符串列表（可选）- 要移除的属性名称
    • add_labels: 字符串列表（可选）- 要添加到实体的标签
    • remove_labels: 字符串列表（可选）- 要从实体移除的标签

示例输入：

{
    "updates": [{
        "id": "john_doe",
        "properties": {
            "occupation": "Senior Developer",
            "salary": 100000
        },
        "remove_properties": ["temporary_note"],
        "add_labels": ["Verified"],
        "remove_labels": ["Pending"]
    }]
}

5. 删除实体

从知识图谱中删除实体，并可选择级联删除关联的关系。

参数：

  • entity_ids: 字符串列表（必填）- 要删除的实体ID列表
  • cascade: 布尔值（可选，默认为 false）- 是否删除关联的关系
  • dry_run: 布尔值（可选，默认为 false）- 预览删除影响而不实际更改

示例输入：

{
    "entity_ids": ["john_doe", "jane_smith"],
    "cascade": true,
    "dry_run": true
}

返回：

{}
  • success: 布尔值 - 操作是否成功
  • deleted_entities: 已删除实体的列表
  • deleted_relationships: 已删除关系的列表
  • errors: 错误消息列表（如果有）
  • impacted_entities: 会受到影响的实体列表（仅在 dry_run 时有效）
  • impacted_relationships: 会受到影响的关系列表（仅在 dry_run 时有效）

6. 反省模式

检索有关 Neo4j 数据库模式的全面信息，包括节点标签、关系类型及其属性。

参数：无需提供

返回：

  • schema: 包含以下内容的对象：
    • node_labels: 数据库中所有节点标签的列表
    • relationship_types: 所有关系类型的列表
    • node_properties: 标签到属性名称列表的映射
    • relationship_properties: 关系类型到属性名称列表的映射

示例输入：

{}

测试

测试脚本

项目包含了针对系统不同方面的多个测试脚本：

  1. mcp_neo4j_knowledge_graph/test_mcp_client.py - 测试 MCP 客户端功能

    • 验证服务器启动
    • 测试工具列表
    • 测试模式反省
    • 测试实体创建
    task test-client  # 仅运行客户端测试

  2. mcp_neo4j_knowledge_graph/test_mcp_config.py - 测试 MCP 配置

    • 验证配置文件加载
    • 使用官方 MCP SDK 测试服务器连接
    • 确认所有必需工具可用
    task test-config  # 仅运行配置测试

  3. mcp_neo4j_knowledge_graph/test_neo4j_connection.py - 测试 Neo4j 数据库连接

    • 验证数据库连通性
    • 测试基本查询功能
    • 检查环境配置
    task test-db  # 仅运行数据库测试

运行测试

你可以通过多种方式运行测试：

  1. 同时运行所有测试：

    task test  # 运行所有测试，包括 pytest 和集成测试

  2. 单独运行特定类型的测试：

    task test-client    # 运行 MCP 客户端测试
task test-config    # 运行 MCP 配置测试
task test-db        # 运行 Neo4j 连接测试
task test-integration  # 运行集成测试

  3. 直接使用 pytest 运行测试：

    poetry run pytest  # 运行所有与 pytest 兼容的测试

开发

使用 Task

项目包含几个开发任务：

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

直接运行

该项目使用了几个开发工具，这些工具会随着 Poetry 自动安装：

  • black 用于代码格式化
  • isort 用于导入排序
  • flake8 用于代码检查
  • pytest 用于测试

你可以使用 Poetry 运行这些工具：

# Format code
poetry run black .

# Sort imports
poetry run isort .

# Run linter
poetry run flake8

# Run tests
poetry run pytest

错误处理

服务器对以下情况进行了全面的错误处理：

  • 数据库连接问题
  • 无效查询
  • 缺失节点
  • 无效请求格式
  • 模式验证错误
  • 关系创建失败
  • 实体更新冲突

所有错误都将以MCP协议格式返回适当的错误消息。

Docker配置

Neo4j容器配置了以下设置：

  • 端口：7474（HTTP）和7687（Bolt）
  • 默认凭据：neo4j/password
  • 启用了APOC插件
  • 文件导入/导出已启用
  • 配置了健康检查

您可以在docker-compose.yml文件中修改这些设置。

任务命令参考

  • task - 显示可用任务
  • task run - 启动Docker和MCP服务器
  • task dev - 启动开发环境（Docker + 服务器 + 测试）
  • task docker - 启动Neo4j数据库
  • task server - 运行MCP服务器
  • task test - 运行所有测试
  • task test-client - 运行MCP客户端测试
  • task test-config - 运行MCP配置测试
  • task test-db - 运行数据库测试
  • task test-integration - 运行集成测试
  • task down - 停止所有Docker服务
  • task format - 使用black和isort格式化代码
  • task lint - 运行flake8 linter
  • task help - 显示所有任务的详细帮助信息

来源