Neo4j MCP服务器
这是一个内存控制协议（MCP）服务器实现，它使用Neo4j作为知识图管理的后端存储。它提供了一个基于stdio的接口，用于以图形数据库格式存储和检索知识。
先决条件
- Python 3.8+
- Neo4j数据库（本地或远程）
- Poetry（Python包管理器）
- Docker和Docker Compose（用于运行Neo4j）
- Go Task（可选，用于任务自动化）
安装
- 克隆存储库：
git clone
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：String-实体的类型（例如，Person、Organization） - properties：对象-实体属性的键值对（必须包含“id”或“name”）
示例输入：
{
"entities": [{
"type": "Person",
"properties": {
"name": "John Doe",
"occupation": "Developer",
"age": 30
}
}]
}2.建立关系
在知识图中的现有实体之间创建关系。在创建关系之前，所有引用的实体都必须存在。
参数：
relations：关系对象列表，每个对象包含：
- type：String-关系类型（例如，KNOWS、WORKS_FOR） - from：String-源实体的ID - to：String-目标实体的ID
示例输入：
{
"relations": [{
"type": "KNOWS",
"from": "john_doe",
"to": "jane_smith"
}]
}3.搜索实体
使用强大的文本匹配和过滤功能在知识图中搜索实体。可用于按文本搜索、按类型列出实体、查找具有特定属性的实体或这些过滤器的任意组合。
参数：
search_term：String（可选）-在实体属性中搜索的文本。如果未提供，则返回基于其他筛选器的实体。entity_type：String（可选）-按实体类型（例如，Person、Organization）筛选结果。如果单独提供，则返回该类型的所有实体。properties：List\[String\]（可选）-要筛选的属性名称列表：
- 使用search_term：在这些属性中搜索术语 - 不带search_term：返回定义了以下任何属性的实体
include_relationships：Boolean（可选，默认值：false）-是否包含连接的实体和关系fuzzy_match：Boolean（可选，默认值：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：String（必填）-要更新的实体的ID - properties：对象（可选）-要更新或添加的属性 - 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：Boolean（可选，默认值：false）-是否删除连接关系dry_run：Boolean（可选，默认值：false）-预览删除影响而不进行更改
示例输入：
{
"entity_ids": ["john_doe", "jane_smith"],
"cascade": true,
"dry_run": true
}退货：
success：Boolean-操作是否成功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客户端功能
- 验证服务器启动 - 测试工具列表 - 测试模式自检 - 测试实体创建
task test-client # Run just the client testmcp_neo4j_knowledge_graph/test_mcp_config.py-测试MCP配置
- 验证配置文件加载 - 使用官方MCP SDK测试服务器连接 - 验证所有必需的工具是否可用
task test-config # Run just the config testmcp_neo4j_knowledge_graph/test_neo4j_connection.py-测试Neo4j数据库连接
- 验证数据库连接 - 测试基本查询功能 - 检查环境配置
task test-db # Run just the database test运行测试
您可以通过多种方式运行测试：
- 一起运行所有测试：
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/密码
- 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-使用黑色和isort格式化代码task lint-运行flake8过梁task help-显示所有任务的详细帮助