Neo4j MCP

A Node.js package that downloads and runs the official Neo4j MCP (Model Context Protocol) server locally. This package automatically detects your system architecture and downloads the appropriate binary from the official Neo4j MCP releases.

Features

• 🔄 Automatic Downloads: Downloads the latest Neo4j MCP server binary for your platform
• 🏗️ Multi-Platform Support: Supports macOS (darwin), Linux, and Windows
• 🎯 Architecture Detection: Automatically detects and downloads the correct architecture (x64, arm64, arm)
• ⚙️ Flexible Configuration: Multiple ways to configure Neo4j connection details
• 🎨 Interactive CLI: User-friendly command-line interface with colored output
• 📦 Caching: Caches downloaded binaries to avoid repeated downloads
• 🔧 Download-Only Mode: Download binary and configure environment variables without starting the server

Installation

npm install -g neo4j-mcp

Or use with npx (no installation required):

npx neo4j-mcp

Usage

Basic Usage

The simplest way to run the Neo4j MCP server is with interactive mode:

npx neo4j-mcp --interactive

This will prompt you for your Neo4j connection details.

Command Line Arguments

You can provide Neo4j connection details directly via command line arguments:

npx neo4j-mcp \
  --uri "bolt://localhost:7687" \
  --username "neo4j" \
  --password "your-password" \
  --database "neo4j"

Environment Variables

Set environment variables in your shell or use a .env file:

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="your-password"
export NEO4J_DATABASE="neo4j"

npx neo4j-mcp

.env File

Create a .env file in your project directory:

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

Then run:

npx neo4j-mcp

Custom .env File

You can specify a custom .env file path:

npx neo4j-mcp --env-file /path/to/your/.env

Command Line Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --uri | -u | Neo4j URI (bolt:// or neo4j://) | bolt://localhost:7687 | | --username | -n | Neo4j username | neo4j | | --password | -p | Neo4j password | password | | --database | -d | Neo4j database name | neo4j | | --env-file | -e | Path to .env file | .env (if exists) | | --interactive | -i | Use interactive mode | false | | --cache-dir | | Directory to cache binaries | ~/.cache/neo4j-mcp | | --version | | Specific version to download | Latest release | | --download-only | | Download binary and set environment variables without starting server | false |

Examples

Interactive Mode

npx neo4j-mcp --interactive

With Custom Cache Directory

npx neo4j-mcp --cache-dir /tmp/neo4j-cache

Specific Version

npx neo4j-mcp --version v0.2.0

Remote Neo4j Instance

npx neo4j-mcp \
  --uri "neo4j://your-neo4j-instance.com:7687" \
  --username "your-username" \
  --password "your-password" \
  --database "your-database"

Download Only (Without Starting Server)

npx neo4j-mcp --download-only

This will download the Neo4j MCP binary and display the environment variables you need to set. This is useful when you want to:

• Download the binary for manual use
• Set up environment variables in your shell
• Integrate the MCP server into your own setup
• Cache the binary without starting the server

The command will output the environment variables and binary path, then exit without starting the server.

Configuration Priority

The configuration is loaded in the following order of priority:

1. Command line arguments (highest priority)
2. Environment variables
3. Interactive prompts (if --interactive is used or required values are missing)
4. Default values (lowest priority)

Supported Platforms

| Platform | Architecture | Status | |----------|-------------|---------| | macOS | x64 (Intel) | ✅ Supported | | macOS | arm64 (Apple Silicon) | ✅ Supported | | Linux | x64 | ✅ Supported | | Linux | arm64 | ✅ Supported | | Linux | arm | ✅ Supported | | Windows | x64 | ✅ Supported | | Windows | arm64 | ✅ Supported |

Requirements

• Node.js 18.0.0 or higher
• Neo4j database instance (local or remote)
• Network access to download binaries from GitHub releases

Troubleshooting

Binary Download Issues

If you encounter issues downloading the binary:

1. Check your internet connection
2. Verify you can access GitHub releases: https://github.com/neo4j/mcp/releases
3. Try clearing the cache directory: rm -rf ~/.cache/neo4j-mcp
4. Check if your platform/architecture combination is supported

Neo4j Connection Issues

If the MCP server fails to connect to Neo4j:

1. Verify your Neo4j instance is running
2. Check that the URI, username, and password are correct
3. Ensure the database name exists in your Neo4j instance
4. Check firewall settings if connecting to a remote instance

Permission Issues

On Unix-like systems, if you get permission errors:

1. Ensure the binary has execute permissions
2. Check that the cache directory is writable
3. Try running with appropriate user permissions

Development

To build and test locally:

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI
npm start

# Development mode with watch
npm run dev

License

MIT

Related Projects

• Official Neo4j MCP Server - The official Model Context Protocol server for Neo4j
• Model Context Protocol - Learn more about MCP

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.