# mcp-neo4j-server

**Repository Path**: yanxxcloud/mcp-neo4j-server

## Basic Information

- **Project Name**: mcp-neo4j-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-29
- **Last Updated**: 2025-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Neo4j Server

一个基于 MCP (Model Context Protocol) 的 Neo4j 图数据库服务器，提供节点和边的增删查改功能。

## 功能特性

- **节点操作**：创建、查询、删除节点
- **关系操作**：创建、查询、删除关系边
- **自定义查询**：支持执行自定义 Cypher 查询
- **环境配置**：支持通过环境变量配置数据库连接
- **错误处理**：完善的错误处理和日志记录

## 安装和设置

### 1. 安装依赖

```bash
# 使用 uv 安装依赖
uv sync
```

### 2. 配置 Neo4j 数据库

复制环境变量示例文件：
```bash
cp .env.example .env
```

编辑 `.env` 文件，配置你的 Neo4j 数据库连接信息：
```bash
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
```

### 3. 启动 Neo4j 数据库

如果你还没有运行 Neo4j 数据库，可以使用 Docker 快速启动：

```bash
docker run \
    --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -d \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/import:/var/lib/neo4j/import \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/password \
    neo4j:latest
```

## 使用方法

### 启动 MCP 服务器

```bash
# 使用 uv 运行
uv run main.py

# 或者直接运行 Python
python main.py
```

### 可用工具

#### 1. 创建节点 (create_node)

创建一个新的图节点。

**参数：**
- `label` (必需): 节点标签
- `properties` (可选): 节点属性（键值对）

**示例：**
```json
{
  "label": "Person",
  "properties": {
    "name": "张三",
    "age": 30,
    "city": "北京"
  }
}
```

#### 2. 创建关系边 (create_edge)

在两个节点之间创建关系。

**参数：**
- `from_node_id` (必需): 起始节点ID
- `to_node_id` (必需): 目标节点ID
- `relationship_type` (必需): 关系类型
- `properties` (可选): 关系属性（键值对）

**示例：**
```json
{
  "from_node_id": 1,
  "to_node_id": 2,
  "relationship_type": "KNOWS",
  "properties": {
    "since": "2020-01-01",
    "strength": "strong"
  }
}
```

#### 3. 查询节点 (query_nodes)

根据条件查询节点。

**参数：**
- `label` (可选): 节点标签
- `properties` (可选): 查询条件（键值对）
- `limit` (可选): 返回结果数量限制，默认10

**示例：**
```json
{
  "label": "Person",
  "properties": {
    "city": "北京"
  },
  "limit": 5
}
```

#### 4. 查询关系边 (query_edges)

根据条件查询关系边。

**参数：**
- `relationship_type` (可选): 关系类型
- `from_node_id` (可选): 起始节点ID
- `to_node_id` (可选): 目标节点ID
- `limit` (可选): 返回结果数量限制，默认10

**示例：**
```json
{
  "relationship_type": "KNOWS",
  "from_node_id": 1,
  "limit": 10
}
```

#### 5. 删除节点 (delete_node)

删除指定节点及其所有关系。

**参数：**
- `node_id` (必需): 要删除的节点ID

**示例：**
```json
{
  "node_id": 1
}
```

#### 6. 删除关系边 (delete_edge)

删除指定的关系边。

**参数：**
- `from_node_id` (必需): 起始节点ID
- `to_node_id` (必需): 目标节点ID
- `relationship_type` (可选): 关系类型

**示例：**
```json
{
  "from_node_id": 1,
  "to_node_id": 2,
  "relationship_type": "KNOWS"
}
```

#### 7. 执行自定义 Cypher 查询 (execute_cypher)

执行自定义的 Cypher 查询语句。

**参数：**
- `query` (必需): Cypher 查询语句
- `parameters` (可选): 查询参数（键值对）

**示例：**
```json
{
  "query": "MATCH (p:Person)-[:KNOWS]->(f:Person) WHERE p.name = $name RETURN f.name as friend_name",
  "parameters": {
    "name": "张三"
  }
}
```

## 项目结构

```
mcp-neo4j-server/
├── main.py              # 主程序文件
├── pyproject.toml       # 项目配置文件
├── .env.example         # 环境变量示例文件
├── .gitignore          # Git 忽略文件
├── .python-version     # Python 版本文件
└── README.md           # 项目说明文档
```

## 技术栈

- **Python 3.11+**: 编程语言
- **MCP (Model Context Protocol)**: 协议框架
- **Neo4j**: 图数据库
- **neo4j-driver**: Neo4j Python 驱动
- **asyncio**: 异步编程支持

## 开发说明

### 日志配置

项目使用 Python 标准库的 `logging` 模块进行日志记录。可以通过环境变量 `LOG_LEVEL` 设置日志级别：

```bash
export LOG_LEVEL=DEBUG  # 可选值：DEBUG, INFO, WARNING, ERROR
```

### 错误处理

所有工具调用都包含完善的错误处理机制：
- 数据库连接错误
- 查询语法错误
- 节点/关系不存在错误
- 参数验证错误

### 扩展功能

如需添加新的工具或功能，可以在 `Neo4jMCPServer` 类中：
1. 在 `_register_tools()` 方法中添加新的工具定义
2. 在 `call_tool()` 方法中添加工具调用逻辑
3. 实现对应的私有方法处理具体逻辑

## 许可证

MIT License