Neo4j MCP 服务器

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

先决条件

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

安装

克隆存储库：

git clone <repository-url>
cd neo4j_mcp_server

如果尚未安装 Poetry，请安装：

curl -sSL https://install.python-poetry.org | python3 -

安装依赖项：

poetry install

配置

Claude桌面配置

对于运行 Claude Desktop 的 Ubuntu 用户，您可以通过将 MCP 服务器添加到您的 Claude 桌面配置文件来配置它：

~/.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"],
      ...
    }
  ]
}

配置包括：

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

运行服务器

使用任务（推荐）

如果您安装了 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

启动 Neo4j 容器：

docker-compose up -d

等待 Neo4j 准备就绪（容器将在docker ps中显示为“健康”）

直接运行 MCP 服务器

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

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

服务器将以 stdio 模式启动，准备接受 MCP 协议消息。

可用工具

1.创建实体

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

参数：

entities ：实体对象列表，每个实体对象包含：
- type ：字符串-实体的类型（例如，个人，组织）
- properties ：对象 - 实体属性的键值对（必须包含“id”或“name”）

示例输入：

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

2.建立关系

在知识图谱中创建现有实体之间的关系。创建关系之前，所有引用的实体必须存在。

参数：

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

示例输入：

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

3. 搜索实体

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

参数：

search_term ：字符串（可选）- 要在实体属性中搜索的文本。如果未提供，则返回基于其他筛选条件的实体。
entity_type ：字符串（可选）- 按实体类型（例如，人员、组织）过滤结果。如果单独提供，则返回该类型的所有实体。
properties ：List [String]（可选） - 要过滤的属性名称列表：
- 使用 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检查属性是否存在
当 fuzz_match 为 true 时，文本搜索支持不区分大小写的部分匹配
空结果将作为空数组返回，而不是错误
性能考虑：
- 按类型过滤比文本搜索更有效
- 优化了属性存在性检查
- 考虑使用特定属性而不是搜索所有属性
- 未来版本中可能会对大型结果集进行分页

4. 更新实体

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

参数：

updates ：更新对象列表，每个更新对象包含：
- id ：字符串（必需） - 要更新的实体的 ID
- properties ：Object（可选）- 要更新或添加的属性
- remove_properties ：List[String]（可选）- 要删除的属性名称
- add_labels ：List[String]（可选）- 要添加到实体的标签
- remove_labels ：List[String]（可选）- 要从实体中删除的标签

示例输入：

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

5.删除实体

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

参数：

entity_ids ：List[String]（必需）- 要删除的实体 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 ：关系类型到属性名称列表的映射

示例输入：

{}

测试

测试脚本

该项目包括针对系统不同方面的几个测试脚本：

mcp_neo4j_knowledge_graph/test_mcp_client.py - 测试 MCP 客户端功能
- 验证服务器启动
- 测试工具列表
- 测试模式自省
- 测试实体创建 GXP18
mcp_neo4j_knowledge_graph/test_mcp_config.py - 测试 MCP 配置
- 验证配置文件加载
- 使用官方 MCP SDK 测试服务器连接
- 验证所有必需工具是否可用 GXP19
mcp_neo4j_knowledge_graph/test_neo4j_connection.py - 测试 Neo4j 数据库连接
- 验证数据库连接
- 测试基本查询功能
- 检查环境配置GXP20

运行测试

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

同时运行所有测试：
task test # Runs all tests including pytest and integration tests
运行单独的测试类型：
task test-client # Run MCP client test task test-config # Run MCP config test task test-db # Run Neo4j connection test task test-integration # Run integration tests
直接使用 pytest 运行测试：
poetry run pytest # Run all pytest-compatible tests

发展

使用任务

该项目包括几个开发任务：

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

直接运行

该项目使用了几个随 Poetry 自动安装的开发工具：

black表示代码格式
isort用于导入排序
flake8用于 linting
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 - 显示所有任务的详细帮助

Neo4j Knowledge Graph

Integrations

Neo4j MCP 服务器

先决条件

安装

配置

Claude桌面配置

运行服务器

使用任务（推荐）

直接使用 Docker Compose

直接运行 MCP 服务器

可用工具

1.创建实体

2.建立关系

3. 搜索实体

4. 更新实体

5.删除实体

6. 自省模式

测试

测试脚本

运行测试

发展

使用任务

直接运行

错误处理

Docker 配置

任务命令参考

Appeared in Searches