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!

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:

   • Open http://localhost:7474
   • Login with credentials from your .env file (default: neo4j/neo4jpassword)

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

Variable	Description	Default
NEO4J_URI	Neo4j connection URI	bolt://localhost:7687
NEO4J_USER	Neo4j username	neo4j
NEO4J_PASSWORD	Neo4j password	password
LOG_LEVEL	Logging level	info

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 LICENSE file for details.

Acknowledgments

• Built with Model Context Protocol SDK
• Powered by Neo4j
• Inspired by the MCP community

---

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.