miltonvve/neo4j-mcp-server

Neo4j MCP Server

🚀 Production-ready Neo4j MCP server with multi-tenancy and Azure AKS deployment

A comprehensive Model Context Protocol (MCP) server for Neo4j that enables seamless integration between Claude Code and Neo4j graph databases. Built with enterprise-grade features including multi-tenancy, project isolation, and production-ready Azure AKS deployment.

✨ Features

🔧 Core Capabilities

• Multi-tenant Architecture - Project isolation with namespace management
• MCP Protocol Support - Full integration with Claude Code and other MCP clients
• Production Ready - Enterprise-grade deployment on Azure AKS
• Type Safety - Built with TypeScript and Zod validation
• Comprehensive Logging - Winston-based logging with audit trails

🛠 Neo4j Integration

• Query Execution - Execute Cypher queries with project isolation
• Node Management - Create, update, and query nodes with labels
• Relationship Management - Build complex graph relationships
• Schema Management - Dynamic schema discovery and validation
• Backup & Restore - Project-specific data export/import

🏗 Infrastructure

• Kubernetes Deployment - Complete AKS manifest files
• SSL/TLS Security - Azure Application Gateway integration
• Monitoring - Prometheus metrics and Grafana dashboards
• Auto-scaling - Horizontal pod autoscaling support
• Health Checks - Comprehensive health monitoring

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm 8+
• Neo4j 5.15+ (Community or Enterprise)
• Claude Code or other MCP client

Installation

# Install via npm
npm install -g neo4j-mcp-server

# Or clone and build
git clone https://github.com/miltonvve/neo4j-mcp-server.git
cd neo4j-mcp-server
npm install
npm run build

Configuration

# Copy environment template
cp .env.example .env

# Edit configuration
vim .env

Basic Usage

# Start the MCP server
neo4j-mcp-server

# Or run in development mode
npm run dev

Claude Integration

Add to your Claude configuration:

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password"
      }
    }
  }
}

🏗 Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    Neo4j MCP Server                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    MCP Protocol    ┌────────────────┐     │
│  │   Claude    │◄─────────────────►│  MCP Server    │     │
│  │    Code     │                    │  (TypeScript)  │     │
│  └─────────────┘                    └────────────────┘     │
│                                              │               │
│                                              │               │
│  ┌─────────────────────────────────────────▼─────────────┐ │
│  │            Project Isolation Layer                   │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │ │
│  │  │ Project A   │  │ Project B   │  │ Project C   │  │ │
│  │  │ Namespace   │  │ Namespace   │  │ Namespace   │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │ │
│  └─────────────────────────────────────────┬─────────────┘ │
│                                              │               │
│  ┌─────────────────────────────────────────▼─────────────┐ │
│  │                Neo4j Database                        │ │
│  │              (Community/Enterprise)                  │ │
│  └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Multi-Tenancy Design

• Project Isolation: Each project gets its own namespace
• Resource Limits: Configurable limits per project
• Audit Logging: All operations tracked per project
• Security: Role-based access control

📋 MCP Tools Reference

Project Management

create_project_namespace

Creates a new project namespace for data isolation.

{
  projectId: string;
  name: string;
  description?: string;
}

Node Operations

create_node

Creates a new node in the specified project namespace.

{
  projectId: string;
  label: string;
  properties: Record<string, any>;
}

Relationship Operations

create_relationship

Creates a relationship between two nodes.

{
  projectId: string;
  fromNode: { label: string; properties: Record<string, any> };
  toNode: { label: string; properties: Record<string, any> };
  relationship: { type: string; properties?: Record<string, any> };
}

Query Operations

execute_cypher_query

Executes a Cypher query within a project namespace.

{
  projectId: string;
  query: string;
  parameters?: Record<string, any>;
}

Utility Operations

get_project_schema

Retrieves schema information for a project.

backup_project

Creates a backup of project data.

🏗 Deployment

Docker Compose (Development)

cd examples/docker-compose
docker-compose up -d

Azure AKS (Production)

# Deploy to Azure
./scripts/deploy-azure.sh

# Setup SSL/TLS
./scripts/setup-ssl.sh

# Health check
./scripts/health-check.sh

For detailed deployment instructions, see:

🔧 Configuration

Environment Variables

Security Configuration

{
  enableProjectIsolation: boolean;
  maxQueryExecutionTime: number;
  allowedLabels?: string[];
  forbiddenQueries?: string[];
}

📊 Monitoring

Metrics

• Query execution times
• Error rates by project
• Connection pool status
• Memory usage
• Request throughput

Logging

• Structured JSON logging
• Audit trail for all operations
• Error tracking and alerting
• Performance monitoring

🧪 Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

🤝 Contributing

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 branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

git clone https://github.com/miltonvve/neo4j-mcp-server.git
cd neo4j-mcp-server
npm install
npm run dev

📚 Documentation

🐛 Troubleshooting

Common Issues

Connection Errors

• Check Neo4j service status
• Verify connection credentials
• Ensure network connectivity

Project Isolation Issues

• Verify project namespace exists
• Check project permissions
• Review audit logs

Performance Issues

• Monitor query execution times
• Check connection pool settings
• Review resource limits

For more help, see

📄 License

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

🙏 Acknowledgments

• Neo4j for the amazing graph database
• Anthropic for Claude and MCP protocol
• Microsoft Azure for cloud infrastructure
• The open-source community for inspiration and contributions

🔗 Links

• Neo4j Documentation
• MCP Protocol Specification
• Azure AKS Documentation
• Claude Code Documentation

Built with ❤️ by GenAI Guru

For questions or support, please open an issue or contact .