# 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](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)
[![Neo4j](https://img.shields.io/badge/neo4j-5.x-brightgreen.svg)](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.