# 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!
[](https://opensource.org/licenses/MIT)
[](https://www.docker.com/)
[](https://neo4j.com/)
## 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:**
```bash
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:**
```bash
docker-compose up -d
```
3. **Verify services are running:**
```bash
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`:
```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:**
```bash
npm install
```
2. **Build the project:**
```bash
npm run build
```
3. **Set environment variables:**
```bash
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password
```
4. **Run the server:**
```bash
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
```bash
npm run build
```
### Development Mode (watch)
```bash
npm run dev
```
### Linting
```bash
npm run lint
```
### Format Code
```bash
npm run format
```
## Docker Commands
```bash
# 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](https://www.patreon.com/c/Roger3333)**
### 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](https://github.com/vpro1032/neo4j-mcp-server/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](LICENSE) file for details.
## Acknowledgments
- Built with [Model Context Protocol SDK](https://github.com/anthropics/mcp)
- Powered by [Neo4j](https://neo4j.com/)
- 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.
