Neo4j MCP 服务器
这是一个内存控制协议 (MCP) 服务器实现，使用 Neo4j 作为知识图谱管理的后端存储。它提供了一个基于 stdio 的接口，用于以图数据库格式存储和检索知识。
先决条件
Python 3.8+
Neo4j 数据库（本地或远程）
Poetry（Python 包管理器）
Docker 和 Docker Compose（用于运行 Neo4j）
Go Task（可选，用于任务自动化）
Related MCP server: MCP Neo4j Knowledge Graph Memory Server
安装
克隆存储库：
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 - 源实体的 IDto：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：字符串（必需） - 要更新的实体的 IDproperties：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用于 lintingpytest用于测试
您可以使用 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 lintertask help- 显示所有任务的详细帮助