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)

Clone and setup:

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

Start the services:
```
docker-compose up -d
```

Verify services are running:

docker-compose ps
docker logs neo4j-mcp-server

Access Neo4j Browser:
- Open http://localhost:7474
- Login with credentials from your .env file (default: neo4j/neo4jpassword)

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"
      ]
    }
  }
}

Restart Claude Desktop and start using Neo4j tools!

Manual Setup (Without Docker)

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Set environment variables:

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

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.