使用说明

Neo4j MCP服务器

用于Neo4j图形数据库操作的生产就绪模型上下文协议（MCP）服务器。该服务器提供了全面的工具，用于在Neo4j中创建、读取、更新和删除节点和关系，以及执行具有完整数据格式的自定义Cypher查询。

🚀 特性

CRUD操作：创建、读取、更新和删除节点和关系
自定义查询：执行任何带有参数和格式化结果的Cypher查询
真实数据库连接：经过验证的连接逻辑，具有强大的错误处理能力
FastMCP实施：采用FastMCP 2.0构建，实现最佳性能
数据格式：正确格式化的结果，显示实际数据
环境管理：通过.env文件进行安全配置
综合测试：具有自动验证功能的完整测试套件
高级分析：图形分析，包括中心性、社区检测和路径分析
RAG支持：使用矢量搜索和语义相似性的检索增强生成

📋 先决条件

Python 3.8+
本地或远程运行的Neo4j数据库
uv 包管理器(MCP配置所需)或 pip （需要手动修改mcp.json）
可选的：用于高级算法的Neo4j图形数据科学（GDS）库

支持GDS的Neo4j部署选项

对于高级图形分析功能，您需要带有GDS扩展的Neo4j。选择以下选项之一：

带GDS扩展的Neo4j桌面 （建议开发）
- 从下载Neo4j桌面 neo4j.com/下载
- 安装图形数据科学库扩展
- 在启用GDS的情况下启动数据库

带有GDS的Docker容器

docker run \
  --name neo4j-gds \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  -e NEO4J_PLUGINS='["graph-data-science"]' \
  neo4j:5.15.0

Neo4j光环 （云托管）
- 在以下位置创建Aura实例 neo4j.com/cloud/platform/aura-graph数据库
- 默认情况下，GDS包含在Aura Professional和Enterprise计划中
使用GDS自托管Neo4j
- 安装Neo4j社区版或企业版
- 从下载并安装GDS库 neo4j.com/docs/graph-data-science/current/installation

🛠️ 安装

克隆存储库:

git clone <repository-url>
cd neo4j_mcp

安装依赖项:
```
uv sync
```
或者使用pip：
```
pip install -r requirements.txt
```
设置环境:
```
cd tests
uv run python setup_env.py
```

⚙️ 配置

环境变量

服务器使用环境变量进行配置。创建一个 .env 项目根目录中的文件：

# Neo4j Database Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

# Logging Configuration
LOG_LEVEL=INFO
DEBUG=false

# MCP Server Configuration
MCP_SERVER_NAME=neo4j-mcp-server

MCP配置

这 mcp.json 文件已配置为使用游标集成 紫外线的 对于环境和包管理：

{
  "mcpServers": {
    "neo4j-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "env": {
        "PYTHONPATH": "E:\\Projects\\neo4j_mcp",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

⚠️ 重要提示：此MCP配置需要 紫外线的 用于环境和包管理。如果你使用的是不同的包管理器（conda、pip等），你需要修改 command 和 args 在 mcp.json 文件与您的特定包管理器配合使用。

其他包管理器示例：

点: "command": "python", "args": ["server.py"]

县: "command": "conda", "args": ["run", "-n", "your-env", "python", "server.py"]

诗歌: "command": "poetry", "args": ["run", "python", "server.py"]

🏃‍♂️ 运行服务器

启动MCP服务器

uv run python server.py

服务器将：

✅ 从.env文件加载环境变量
✅ 启动时测试Neo4j连接
✅ 使用stdio传输启动MCP服务器
✅ 显示带有实际数据的格式化结果

期望输出

Loaded environment variables from .env file
INFO:__main__:DEBUG: Connecting to Neo4j at bolt://localhost:7687 as neo4j to database neo4j

🛠️ 可用工具

核心业务

echo(message: str) -回显消息（用于测试）
create_node(labels: List[str], properties: Optional[Dict]) -创建新节点
list_nodes(label: Optional[str]) -列出具有格式化结果的节点
create_relationship(from_node_id: str, to_node_id: str, relationship_type: str, properties: Optional[Dict]) -建立关系
execute_query(query: str, parameters: Optional[Dict]) -使用格式化结果执行自定义Cypher查询

高级操作

get_node(node_id: Optional[int], labels: Optional[List[str]], properties: Optional[Dict]) -按条件获取节点
update_node(node_id: int, properties: Optional[Dict], labels: Optional[List[str]]) -更新节点
delete_node(node_id: int, cascade: bool) -删除节点

高级分析

graph_analytics(analysis_type: str, node_label: Optional[str], relationship_type: Optional[str]) -执行图形分析
- degree_centrality -查找连接数最高的节点
- betweenness_centrality -查找充当网桥的节点（GDS或APOC）
- community_detection -在图中检测社区（GDS Louvain或本地）
- pagerank -测量节点重要性和影响（GDS或APOC）
- node_similarity -基于关系（GDS或原生）查找相似节点
- clustering_coefficient -测量本地聚类（GDS或APOC）
- path_analysis -分析节点之间的最短路径
graph_statistics() -获取全面的图形统计数据

图形数据科学（GDS）支持

create_graph_projection(graph_name: str, node_labels: Optional[List[str]], relationship_types: Optional[List[str]]) -为GDS算法创建图形投影
list_graph_projections() -列出所有可用的图形投影
drop_graph_projection(graph_name: str) -删除图形投影

GDS算法可用 （安装Neo4j GDS库时）：

鲁汶社区检测：基于模块化的高级集群
GDS页面排名：优化PageRank实现
GDS中间中心：快速介数计算
GDS节点相似性：高效的相似性算法
GDS局部聚类系数：高级聚类指标

回退算法 （当GDS不可用时）：

APOC网页排名：使用APOC库算法
本地Cypher：使用内置的Cypher查询
APOC三角计数：基本聚类系数

备注：GDS需要带GDS扩展的Neo4j Desktop、带GDS插件的Docker、Neo4j Aura或安装了GDS库的自托管Neo4j。

RAG（检索增强生成）

create_vector_index(index_name: str, node_label: str, property_name: str, dimensions: int) -为语义搜索创建向量索引
semantic_search(query_vector: List[float], index_name: str, limit: int) -使用向量相似度执行语义搜索
hybrid_search(text_query: str, node_label: str, vector_property: str, text_properties: List[str], limit: int) -结合文本和矢量搜索
create_embedding_node(node_label: str, name: str, description: str, embedding: List[float]) -创建带有嵌入的节点
rag_context_retrieval(query: str, node_label: str, context_properties: List[str], limit: int) -检索RAG的相关上下文

🧪 测试

运行完整的测试套件

cd tests
uv run python test_suite.py

运行单独测试

# Verify MCP server functionality
uv run python verify_mcp.py

# Setup environment
uv run python setup_env.py

📊 测试结果

测试套件将输出：

✅ 成功测试通过
❌ 测试失败，失败
调试的详细错误消息

🔧 最近的改进

✅ 已实现的功能

数据格式：添加了正确的结果格式和实际数据显示
环境管理：使用python dotenv通过.env文件进行安全配置
综合测试：具有自动验证功能的完整测试套件
工具整合：组织的所有测试 /tests 目录
错误处理：具有真实错误消息的稳健错误处理
连接逻辑：经过验证的连接逻辑，具有适当的驱动程序生命周期管理
GDS集成：完整的图形数据科学库支持，功能经过验证
高级分析：使用GDS算法和回退进行全面的图形分析
MLB数据库：完整的2025年美国职业棒球大联盟赛季数据库，包括球队、比赛、球员和盒子分数
社区发现：使用现实的团队集群进行Louvain社区检测

🔄 关键改进

数据显示：工具现在显示实际的格式化数据，而不仅仅是成功消息
环境设置：自动创建和验证.env文件
测试组织：将所有测试整合到一个结构化的测试套件中
文档：更新了安装和配置说明

📁 项目结构

neo4j_mcp/
├── server.py                 # Main MCP server implementation
├── mcp.json                  # MCP configuration for Cursor
├── requirements.txt          # Python dependencies
├── README.md                # This documentation
├── LICENSE                  # MIT License
├── TRD_Neo4j_MCP_Server.md  # Technical Requirements Document
├── tests/                   # Test suite directory
│   ├── test_suite.py        # Comprehensive test suite
│   ├── verify_mcp.py        # MCP server verification
│   ├── setup_env.py         # Environment setup helper
│   └── README.md           # Test documentation
└── .env                     # Environment variables (created by setup)

🐛 故障排除

常见问题

连接失败：确保Neo4j正在运行并且凭据正确
MCP工具没有响应：重新启动MCP服务器和游标
环境变量：检查一下 .env 文件存在并已配置
测试失败：运行测试套件以确定具体问题

调试步骤

运行测试套件: cd tests && uv run python test_suite.py
检查环境: cd tests && uv run python setup_env.py
验证MCP服务器: cd tests && uv run python verify_mcp.py
检查服务器日志：在服务器输出中查找连接消息

🚀 使用示例

与光标一起使用

配置后，您可以在Cursor中使用MCP工具：

mcp_neo4j-mcp-server_list_nodes
mcp_neo4j-mcp-server_create_node
mcp_neo4j-mcp-server_execute_query

查询示例

# Create a movie node
CREATE (m:Movie {title: 'Dune', director: 'Denis Villeneuve', year: 2021})

# List all movies
MATCH (m:Movie) RETURN m.title, m.director, m.year

# Find relationships
MATCH (m1:Movie)-[r:SIMILAR_GENRE]->(m2:Movie) RETURN m1.title, m2.title

高级分析示例

# Degree centrality analysis
mcp_neo4j-mcp-server_graph_analytics(analysis_type="degree_centrality", node_label="Movie")

# Community detection (GDS Louvain or native fallback)
mcp_neo4j-mcp-server_graph_analytics(analysis_type="community_detection")

# PageRank analysis (GDS or APOC fallback)
mcp_neo4j-mcp-server_graph_analytics(analysis_type="pagerank")

# Node similarity (GDS or native fallback)
mcp_neo4j-mcp-server_graph_analytics(analysis_type="node_similarity")

# Clustering coefficient (GDS or APOC fallback)
mcp_neo4j-mcp-server_graph_analytics(analysis_type="clustering_coefficient")

# Path analysis
mcp_neo4j-mcp-server_graph_analytics(analysis_type="path_analysis", relationship_type="STARRED_IN")

# Get graph statistics
mcp_neo4j-mcp-server_graph_statistics()

图形数据科学（GDS）示例

# Create a graph projection for GDS algorithms
mcp_neo4j-mcp-server_create_graph_projection(graph_name="movie_actor_graph", node_labels=["Movie", "Actor"], relationship_types=["STARRED_IN"])

# List available graph projections
mcp_neo4j-mcp-server_list_graph_projections()

# Run GDS algorithms on the projection
mcp_neo4j-mcp-server_graph_analytics(analysis_type="community_detection")  # Uses GDS Louvain
mcp_neo4j-mcp-server_graph_analytics(analysis_type="pagerank")  # Uses GDS PageRank

# Drop a graph projection when done
mcp_neo4j-mcp-server_drop_graph_projection(graph_name="movie_actor_graph")

RAG示例

# Create vector index
mcp_neo4j-mcp-server_create_vector_index(index_name="movie_embeddings", node_label="Movie", property_name="embedding")

# Semantic search
mcp_neo4j-mcp-server_semantic_search(query_vector=[0.1, 0.2, ...], index_name="movie_embeddings")

# Hybrid search
mcp_neo4j-mcp-server_hybrid_search(text_query="sci-fi", node_label="Movie", vector_property="embedding", text_properties=["title", "description"])

# RAG context retrieval
mcp_neo4j-mcp-server_rag_context_retrieval(query="space exploration", node_label="Movie", context_properties=["title", "description"])

🤝 贡献

这是一个生产就绪的实现，具有全面的测试和文档。该项目遵循MCP开发和Neo4j集成的最佳实践。

📄 许可证

这个项目是开源的，可以在MIT许可证下使用。