neo4j-mcp-server

vpro1032/neo4j-mcp-server

3.2

If you are the rightful owner of neo4j-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Neo4j MCP Server is a Model Context Protocol server that integrates AI assistants with Neo4j graph databases, enabling natural language interaction with knowledge graphs.

Tools
10
Resources
0
Prompts
0

Neo4j MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between AI assistants (like Claude Desktop) and Neo4j graph databases. Query and manipulate your knowledge graphs using natural language!

License: MIT Docker Neo4j

Features

  • Direct Cypher Queries: Execute Cypher queries directly from your AI assistant
  • Natural Language Queries: Convert natural language questions into Cypher (template-based, LLM integration ready)
  • Schema Operations: View, create, and manage database schema (constraints, indexes)
  • Data Manipulation: Create nodes and relationships
  • Graph Algorithms: PageRank, shortest path, and more
  • Admin Tools: Get database statistics and health info
  • 100% Local: All data stays on your infrastructure
  • Docker Ready: Easy deployment with Docker Compose

Quick Start

Prerequisites

  • Docker Desktop running
  • Node.js 20+ (for local development)
  • Basic knowledge of Neo4j/Cypher

Using Docker Compose (Recommended)

  1. Clone and setup:

    git clone <your-repo-url>
cd neo4j-mcp
cp .env.example .env
# Edit .env if you want to change default password

  2. Start the services:

    docker-compose up -d

  3. Verify services are running:

    docker-compose ps
docker logs neo4j-mcp-server

  4. Access Neo4j Browser:

  5. Configure Claude Desktop:

    Add to your claude_desktop_config.json:

    {
  "mcpServers": {
    "neo4j": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "neo4j-mcp-server",
        "node",
        "/app/dist/index.js"
      ]
    }
  }
}

  6. Restart Claude Desktop and start using Neo4j tools!

Manual Setup (Without Docker)

  1. Install dependencies:

    npm install

  2. Build the project:

    npm run build

  3. Set environment variables:

    export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password

  4. Run the server:

    npm start

Available MCP Tools

Once connected to Claude Desktop, you can use these tools:

Query Tools

  • neo4j.query - Execute raw Cypher queries
  • neo4j.natural_query - Convert natural language to Cypher (template-based)

Schema Tools

  • neo4j.get_schema - Get database schema
  • neo4j.create_constraint - Create constraints (UNIQUE, EXISTS, NODE_KEY)
  • neo4j.create_index - Create indexes (BTREE, TEXT, RANGE, POINT)

Data Tools

  • neo4j.create_node - Create nodes with labels and properties
  • neo4j.create_relationship - Create relationships between nodes

Algorithm Tools

  • neo4j.page_rank - Calculate PageRank scores
  • neo4j.shortest_path - Find shortest paths between nodes

Admin Tools

  • neo4j.get_stats - Get database statistics

Usage Examples

Example 1: Ask Claude to query your graph

You: "Show me all Person nodes in the database"
Claude: Uses neo4j.query tool

Example 2: Create data

You: "Create a Person node with name 'Alice' and age 30"
Claude: Uses neo4j.create_node tool

Example 3: Schema management

You: "Create a unique constraint on Person.email"
Claude: Uses neo4j.create_constraint tool

Configuration

Environment Variables

VariableDescriptionDefault
NEO4J_URINeo4j connection URIbolt://localhost:7687
NEO4J_USERNeo4j usernameneo4j
NEO4J_PASSWORDNeo4j passwordpassword
LOG_LEVELLogging levelinfo

Docker Compose

The default docker-compose.yml includes:

  • Neo4j 5 with APOC plugin
  • MCP Server connected to Neo4j
  • Persistent volumes for data
  • Health checks

Project Structure

neo4j-mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── neo4j/
│   │   └── connection.ts     # Neo4j connection management
│   ├── query/
│   │   └── engine.ts         # Natural language to Cypher engine
│   ├── tools/
│   │   ├── index.ts          # Tool registration
│   │   ├── query.ts          # Query tools
│   │   ├── schema.ts         # Schema tools
│   │   ├── data.ts           # Data manipulation tools
│   │   ├── algorithms.ts     # Graph algorithm tools
│   │   └── admin.ts          # Admin tools
│   └── utils/
│       └── validation.ts     # Input validation utilities
├── dist/                     # Compiled JavaScript (generated)
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Docker Compose configuration
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment variables template
└── README.md                 # This file

Development

Build

npm run build

Development Mode (watch)

npm run dev

Linting

npm run lint

Format Code

npm run format

Docker Commands

# Start services
docker-compose up -d

# View logs
docker-compose logs -f neo4j-mcp

# Stop services
docker-compose down

# Stop and remove volumes (deletes data!)
docker-compose down -v

# Rebuild after code changes
docker-compose build neo4j-mcp
docker-compose up -d neo4j-mcp

Roadmap

  • Full LLM integration for natural language queries (OpenAI, Anthropic, Ollama)
  • Advanced query optimization
  • Caching layer (Redis)
  • More graph algorithms (community detection, centrality measures)
  • Graph visualization support
  • Batch operations and CSV import
  • Multi-database support
  • Kubernetes deployment manifests

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Support This Project

If you find this Neo4j MCP Server useful for your projects, please consider supporting its development!

☕ Become a Patron

This project is maintained by independent developers. Your support helps us:

  • 🚀 Add new features and improvements
  • 🐛 Fix bugs and improve stability
  • 📚 Create better documentation and tutorials
  • 🔒 Enhance security features
  • 🎯 Provide faster support and updates

Support us on Patreon

Supporter Benefits

Patrons get access to:

  • 🎯 Priority Support - Get help faster when you need it
  • 📝 Early Access - Try new features before public release
  • 💬 Direct Communication - Influence the project roadmap
  • 🎓 Exclusive Tutorials - Advanced usage guides and examples
  • 🏆 Recognition - Your name in our SUPPORTERS.md file

Other Ways to Support

  • ⭐ Star this repository on GitHub
  • 🐛 Report bugs and request features via GitHub Issues
  • 📖 Improve documentation by submitting pull requests
  • 💬 Spread the word - Share with colleagues and on social media

License

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

Acknowledgments

Note: This is an open-source project under active development. The natural language query feature currently uses template-based matching. Full LLM integration is planned for future releases.