npm package: @johnymontana/neo4j-mcp
Description: Node.js package to download and run the official Neo4j MCP server
Author: William Lyon
Latest version: 0.0.2

# 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](https://github.com/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

```bash
npm install -g neo4j-mcp
```

Or use with npx (no installation required):

```bash
npx neo4j-mcp
```

## Usage

### Basic Usage

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

```bash
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:

```bash
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:

```bash
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:

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

Then run:

```bash
npx neo4j-mcp
```

### Custom .env File

You can specify a custom .env file path:

```bash
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
```bash
npx neo4j-mcp --interactive
```

### With Custom Cache Directory
```bash
npx neo4j-mcp --cache-dir /tmp/neo4j-cache
```

### Specific Version
```bash
npx neo4j-mcp --version v0.2.0
```

### Remote Neo4j Instance
```bash
npx neo4j-mcp \
  --uri "neo4j://your-neo4j-instance.com:7687" \
  --username "your-username" \
  --password "your-password" \
  --database "your-database"
```

### Download Only (Without Starting Server)
```bash
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:

```bash
# 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](https://github.com/neo4j/mcp) - The official Model Context Protocol server for Neo4j
- [Model Context Protocol](https://modelcontextprotocol.io/) - Learn more about MCP

## Contributing

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