neo4j2llm (Michaelhil)

neo4j2LLM

🚀 用于Neo4j知识图与Claude桌面集成的MCP服务器

基于TypeScript的模型上下文协议（MCP）服务器，使Claude Desktop能够直接与Neo4j知识图交互。采用现代技术打造，性能可靠，易于使用。

📋 目录

• 特性
• 先决条件
• 安装
• 配置
• 用法
• 可用工具
• 例子
• 建筑
• 发展
• 码头工人
• 贡献
• 许可证

✨ 特性

• 🔌 通用Neo4j连接 -适用于本地、Docker、云和AuraDB实例
• 🛠️ 综合工具集 -知识图谱操作的12个基本工具
• ⚡ 高性能 -使用Bun运行时和优化的TypeScript构建
• 🔒 设计安全 -强大的验证、错误处理和连接管理
• 📊 丰富的查询分析 -查询分析、执行计划和优化提示
• 🎯 类型安全 -100%TypeScript，具有全面的类型定义
• 🔄 实时操作 -对大型数据集的流媒体支持
• 📈 图式反思 -完成数据库模式分析和可视化

📋 先决条件

• Node.js >=18.0.0或 包子 >= 1.0.0
• Neo4j数据库 （本地安装、Docker或云实例）
• 克劳德桌面 支持MCP

🚀 安装

选项1：使用Bun（推荐）

# Clone the repository
git clone https://github.com/michaelhil/neo4j2llm.git
cd neo4j2llm

# Install dependencies
bun install

# Build the project
bun run build

# Run the MCP server
bun run src/index.ts

选项2：使用npm

# Clone and install
git clone https://github.com/michaelhil/neo4j2llm.git
cd neo4j2llm
npm install

# Build and run
npm run build
npm start

选项3：Docker容器

# Pull and run the container
docker run -it --rm \\
  -e NEO4J_URI=bolt://host.docker.internal:7687 \\
  -e NEO4J_USERNAME=neo4j \\
  -e NEO4J_PASSWORD=password \\
  michaelhil/neo4j2llm:latest

⚙️ 配置

环境变量

创建一个 .env 根目录中的文件：

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

Claude桌面配置

添加到您的Claude Desktop MCP设置中：

{
  "mcpServers": {
    "neo4j2llm": {
      "command": "bun",
      "args": ["run", "/path/to/neo4j2llm/src/index.ts"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

连接选项

服务器支持多种Neo4j部署类型：

📖 用法

配置后，您可以使用Claude的自然语言与Neo4j数据库进行交互：

基本连接

Connect to my Neo4j database at bolt://localhost:7687 with username neo4j and password mypassword

查询执行

Show me all Person nodes in the database

模式探索

What labels and relationship types exist in my database?

数据创建

Create a new Person node with name "Alice" and age 30

性能分析

Explain the execution plan for: MATCH (p:Person)-[:KNOWS]->(f:Person) RETURN p, f

🛠️ 可用工具

🔌 连接管理

neo4j_connect

建立与Neo4j数据库实例的连接。

参数：

• uri （必填）：Neo4j连接URI
• username （必填）：数据库用户名
• password （必填）：数据库密码
• database （可选）：目标数据库名称
• maxConnectionPoolSize （可选）：最大连接池大小
• connectionTimeout （可选）：连接超时（毫秒）

例子：

{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "movies"
}

neo4j_disconnect

关闭与Neo4j数据库的连接。

例子：

// No parameters required

neo4j_test_connection

测试连接健康状况并获取数据库信息。

参数：

• includePerformanceTest （可选）：包括响应时间测量

例子：

{
  "includePerformanceTest": true
}

🔍 查询执行

neo4j_execute_query

对Neo4j数据库执行Cypher查询。

参数：

• cypher （必填）：密码查询字符串
• parameters （可选）：查询参数
• timeout （可选）：查询超时（毫秒）
• includeStats （可选）：包括执行统计信息
• limit （可选）：要返回的最大记录数

例子：

{
  "cypher": "MATCH (p:Person {name: $name}) RETURN p",
  "parameters": {"name": "Alice"},
  "limit": 100,
  "includeStats": true
}

neo4j_explain_query

获取Cypher查询的执行计划，而不执行它。

参数：

• cypher （必填）：密码查询说明
• parameters （可选）：查询参数

例子：

{
  "cypher": "MATCH (p:Person)-[:KNOWS]->(f) RETURN p, f",
  "parameters": {}
}

neo4j_profile_query

执行并分析Cypher查询以分析性能。

参数：

• cypher （必填）：通过密码查询个人资料
• parameters （可选）：查询参数

例子：

{
  "cypher": "MATCH (p:Person) WHERE p.age > $minAge RETURN count(p)",
  "parameters": {"minAge": 25}
}

📊 模式管理

neo4j_get_schema

检索完整的数据库模式，包括标签、关系、属性、约束和索引。

参数：

• includeStatistics （可选）：包括架构统计信息
• includePropertyInfo （可选）：包括详细的房产信息

例子：

{
  "includeStatistics": true,
  "includePropertyInfo": true
}

neo4j_get_labels

获取所有节点标签及其计数和示例属性。

参数：

• includeCounts （可选）：包括每个标签的节点计数
• includeSampleProperties （可选）：包括示例属性名称
• sortBy （可选）：按“名称”或“计数”排序
• limit （可选）：要返回的最大标签数

例子：

{
  "includeCounts": true,
  "sortBy": "count",
  "limit": 50
}

neo4j_get_relationship_types

获取所有关系类型及其计数和示例属性。

参数：

• includeCounts （可选）：包括关系计数
• includeSampleProperties （可选）：包括示例属性名称
• sortBy （可选）：按“名称”或“计数”排序
• limit （可选）：要返回的最大类型数

例子：

{
  "includeCounts": true,
  "includeSampleProperties": true,
  "sortBy": "name"
}

🏗️ 图形创建

neo4j_create_nodes

使用指定的标签和属性创建多个节点。

neo4j_create_relationships

在具有指定属性的现有节点之间创建关系。

📤 数据导出

neo4j_export_data

以JSON、CSV或Cypher格式导出查询结果。

参数：

• nodes （必需）：要创建的节点数组
• returnCreated （可选）：返回已创建节点的信息
• batchSize （可选）：每批要创建的节点数

示例-创建节点：

{
  "nodes": [
    {
      "labels": ["Person"],
      "properties": {"name": "Alice", "age": 30}
    },
    {
      "labels": ["Person", "Developer"],
      "properties": {"name": "Bob", "age": 25, "skill": "TypeScript"}
    }
  ],
  "returnCreated": true,
  "batchSize": 100
}

示例-创建关系：

{
  "relationships": [
    {
      "type": "KNOWS",
      "properties": {"since": "2020"},
      "startNode": {
        "labels": ["Person"],
        "properties": {"name": "Alice"}
      },
      "endNode": {
        "labels": ["Person"],
        "properties": {"name": "Bob"}
      }
    }
  ],
  "returnCreated": true
}

示例-导出数据：

{
  "query": "MATCH (p:Person) RETURN p.name, p.age",
  "format": "json",
  "limit": 100
}

💡 例子

1.基础数据库探索

// Connect to database
await neo4j_connect({
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password"
})

// Get database schema
await neo4j_get_schema({
  "includeStatistics": true
})

// List all labels
await neo4j_get_labels({
  "includeCounts": true,
  "sortBy": "count"
})

2.查询性能分析

// Profile a complex query
await neo4j_profile_query({
  "cypher": `
    MATCH (p:Person)-[:WORKS_FOR]->(c:Company)
    WHERE c.industry = $industry
    RETURN p.name, c.name
    ORDER BY p.name
  `,
  "parameters": {"industry": "Technology"}
})

3.数据创建和查询

// Create nodes
await neo4j_create_nodes({
  "nodes": [
    {
      "labels": ["Company"],
      "properties": {"name": "TechCorp", "industry": "Technology"}
    },
    {
      "labels": ["Person"],
      "properties": {"name": "Alice", "role": "Engineer"}
    }
  ],
  "returnCreated": true
})

// Query the created data
await neo4j_execute_query({
  "cypher": "MATCH (p:Person {name: 'Alice'}) RETURN p",
  "includeStats": true
})

🏗️ 建筑

系统概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│                 │    │                  │    │                 │
│  Claude Desktop │◄──►│   neo4j2LLM      │◄──►│   Neo4j         │
│                 │    │   MCP Server     │    │   Database      │
│                 │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

技术栈

• 🔧 运行时：Bun（主要）/Node.js（兼容）
• 📝 语言：TypeScript（100%）
• 🔌 协议：模型上下文协议（MCP）
• 🗄️ 数据库：Neo4j（所有版本）
• 🧪 测试：丁腈橡胶试运行器
• 📦 建筑：快
• 🔍 代码检查：ESLint+TypeScript规则

项目结构

neo4j2LLM/
├── src/
│   ├── core/              # Core types, errors, validation
│   ├── connection/        # Neo4j connection management
│   ├── services/          # Business logic services
│   ├── tools/             # MCP tool implementations
│   │   ├── connection/    # Connection management tools
│   │   ├── query/         # Query execution tools
│   │   ├── schema/        # Schema introspection tools
│   │   └── creation/      # Data creation tools
│   └── index.ts          # MCP server entry point
├── docs/                 # Documentation
├── tests/                # Test suites
└── docker/               # Docker configuration

关键设计原则

• 🏗️ 工厂模式：所有服务都使用工厂函数进行干净的实例化
• 🛡️ 类型安全：全面的TypeScript接口和验证
• 🔄 函数式编程：不可变的数据结构和纯函数
• 🚦 错误处理：强大的错误分类和恢复
• ⚡ 演出：连接池、查询优化和流媒体支持

🧪 发展

设置开发环境

# Clone and install
git clone https://github.com/michaelhil/neo4j2llm.git
cd neo4j2llm
bun install

# Start development server
bun run dev

# Run tests
bun test

# Type checking
bun run type-check

# Linting
bun run lint

项目脚本

bun run dev          # Development server with hot reload
bun run build        # Build for production
bun test             # Run test suite
bun test:watch       # Run tests in watch mode
bun run lint         # Lint code
bun run lint:fix     # Fix linting issues
bun run type-check   # TypeScript type checking

测试

# Run all tests
bun test

# Run specific test file
bun test src/tools/connection/connect.test.ts

# Run tests with coverage
bun test --coverage

🐳 码头工人

建造集装箱

# Build the Docker image
docker build -t neo4j2llm .

# Run the container
docker run -it --rm \\
  -e NEO4J_URI=bolt://host.docker.internal:7687 \\
  -e NEO4J_USERNAME=neo4j \\
  -e NEO4J_PASSWORD=password \\
  neo4j2llm

Docker Compose

version: '3.8'
services:
  neo4j:
    image: neo4j:latest
    environment:
      NEO4J_AUTH: neo4j/password
    ports:
      - "7474:7474"
      - "7687:7687"

  neo4j2llm:
    build: .
    environment:
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_USERNAME: neo4j
      NEO4J_PASSWORD: password
    depends_on:
      - neo4j

🤝 贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

开发工作流程

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

代码规范

• TypeScript 适用于所有代码（无JavaScript文件）
• ESLint 代码质量
• 更漂亮 用于格式化
• 综合测试 对于新功能
• 文档 适用于所有公共API

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• Neo4j团队 优秀的图形数据库
• Anthropic 克劳德和MCP协议
• Bun团队 运行速度极快
• TypeScript团队 卓越的型式安全

📞 支持

• 问题:
• 讨论:
• 文档: 维基工程

______________________________________________________________________

由以下材料制成❤️ 知识图谱社区