michaelhil/neo4j2llm

neo4j2LLM

🚀 MCP Server for Neo4j Knowledge Graph Integration with Claude Desktop

A TypeScript-based Model Context Protocol (MCP) server that enables Claude Desktop to interact directly with Neo4j knowledge graphs. Built with modern technologies for performance, reliability, and ease of use.

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Available Tools
• Examples
• Architecture
• Development
• Docker
• Contributing
• License

✨ Features

• 🔌 Universal Neo4j Connectivity - Works with local, Docker, cloud, and AuraDB instances
• 🛠️ Comprehensive Toolset - 12 essential tools for knowledge graph operations
• ⚡ High Performance - Built with Bun runtime and optimized TypeScript
• 🔒 Secure by Design - Robust validation, error handling, and connection management
• 📊 Rich Query Analysis - Query profiling, execution plans, and optimization tips
• 🎯 Type Safety - 100% TypeScript with comprehensive type definitions
• 🔄 Real-time Operations - Streaming support for large datasets
• 📈 Schema Introspection - Complete database schema analysis and visualization

📋 Prerequisites

• Node.js >= 18.0.0 or Bun >= 1.0.0
• Neo4j Database (local installation, Docker, or cloud instance)
• Claude Desktop with MCP support

🚀 Installation

Option 1: Using Bun (Recommended)

# 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

Option 2: Using npm

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

# Build and run
npm run build
npm start

Option 3: Docker Container

# 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

⚙️ Configuration

Environment Variables

Create a .env file in the root directory:

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

Claude Desktop Configuration

Add to your Claude Desktop MCP settings:

{
  "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"
      }
    }
  }
}

Connection Options

The server supports multiple Neo4j deployment types:

📖 Usage

Once configured, you can use natural language with Claude to interact with your Neo4j database:

Basic Connection

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

Query Execution

Show me all Person nodes in the database

Schema Exploration

What labels and relationship types exist in my database?

Data Creation

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

Performance Analysis

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

🛠️ Available Tools

🔌 Connection Management

neo4j_connect

Establish connection to Neo4j database instance.

Parameters:

• uri (required): Neo4j connection URI
• username (required): Database username
• password (required): Database password
• database (optional): Target database name
• maxConnectionPoolSize (optional): Max connection pool size
• connectionTimeout (optional): Connection timeout in milliseconds

Example:

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

neo4j_disconnect

Close connection to Neo4j database.

Example:

// No parameters required

neo4j_test_connection

Test connection health and get database information.

Parameters:

• includePerformanceTest (optional): Include response time measurement

Example:

{
  "includePerformanceTest": true
}

🔍 Query Execution

neo4j_execute_query

Execute Cypher query against Neo4j database.

Parameters:

• cypher (required): Cypher query string
• parameters (optional): Query parameters
• timeout (optional): Query timeout in milliseconds
• includeStats (optional): Include execution statistics
• limit (optional): Maximum records to return

Example:

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

neo4j_explain_query

Get execution plan for Cypher query without executing it.

Parameters:

• cypher (required): Cypher query to explain
• parameters (optional): Query parameters

Example:

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

neo4j_profile_query

Execute and profile Cypher query to analyze performance.

Parameters:

• cypher (required): Cypher query to profile
• parameters (optional): Query parameters

Example:

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

📊 Schema Management

neo4j_get_schema

Retrieve complete database schema including labels, relationships, properties, constraints, and indexes.

Parameters:

• includeStatistics (optional): Include schema statistics
• includePropertyInfo (optional): Include detailed property information

Example:

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

neo4j_get_labels

Get all node labels with their counts and sample properties.

Parameters:

• includeCounts (optional): Include node counts for each label
• includeSampleProperties (optional): Include sample property names
• sortBy (optional): Sort by 'name' or 'count'
• limit (optional): Maximum number of labels to return

Example:

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

neo4j_get_relationship_types

Get all relationship types with their counts and sample properties.

Parameters:

• includeCounts (optional): Include relationship counts
• includeSampleProperties (optional): Include sample property names
• sortBy (optional): Sort by 'name' or 'count'
• limit (optional): Maximum number of types to return

Example:

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

🏗️ Graph Creation

neo4j_create_nodes

Create multiple nodes with specified labels and properties.

neo4j_create_relationships

Create relationships between existing nodes with specified properties.

📤 Data Export

neo4j_export_data

Export query results in JSON, CSV, or Cypher format.

Parameters:

• nodes (required): Array of nodes to create
• returnCreated (optional): Return information about created nodes
• batchSize (optional): Number of nodes to create per batch

Example - Creating Nodes:

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

Example - Creating Relationships:

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

Example - Exporting Data:

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

💡 Examples

1. Basic Database Exploration

// 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. Query Performance Analysis

// 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. Data Creation and Querying

// 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
})

🏗️ Architecture

System Overview

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

Technology Stack

• 🔧 Runtime: Bun (primary) / Node.js (compatible)
• 📝 Language: TypeScript (100%)
• 🔌 Protocol: Model Context Protocol (MCP)
• 🗄️ Database: Neo4j (all versions)
• 🧪 Testing: Bun test runner
• 📦 Building: Vite
• 🔍 Linting: ESLint + TypeScript rules

Project Structure

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

Key Design Principles

• 🏗️ Factory Pattern: All services use factory functions for clean instantiation
• 🛡️ Type Safety: Comprehensive TypeScript interfaces and validation
• 🔄 Functional Programming: Immutable data structures and pure functions
• 🚦 Error Handling: Robust error categorization and recovery
• ⚡ Performance: Connection pooling, query optimization, and streaming support

🧪 Development

Setup Development Environment

# 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

Project Scripts

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

Testing

# Run all tests
bun test

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

# Run tests with coverage
bun test --coverage

🐳 Docker

Building the Container

# 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

🤝 Contributing

We welcome contributions! Please see for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Standards

• TypeScript for all code (no JavaScript files)
• ESLint for code quality
• Prettier for formatting
• Comprehensive tests for new features
• Documentation for all public APIs

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Neo4j Team for the excellent graph database
• Anthropic for Claude and the MCP protocol
• Bun Team for the blazing fast runtime
• TypeScript Team for type safety excellence

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

Made with ❤️ for the Knowledge Graph community