Neo4j Web Bridge

Lightweight Proxy für Browser-Zugriff auf selbst-gehostete Neo4j Datenbanken. Löst das TLS-Problem bei Railway, Render, Fly.io und anderen Plattformen.

Zero TLS Config

Verbinden ohne Zertifikate

Überall nutzbar

Railway, Render, Fly.io, Docker

REST API

Für LLMs und Automatisierung

Open Source

MIT Lizenz, selbst hosten

Das Problem

Browser erzwingen HTTPS. Neo4j Bolt ist standardmäßig unverschlüsselt (bolt://). Cloud-Plattformen terminieren TLS nur für HTTP, nicht für TCP-Ports wie Bolt 7687.

Ergebnis: Neo4j Browser kann sich nicht verbinden.

Die Lösung

Browser (HTTPS) → Neo4j Web Bridge → Neo4j (bolt://)
                   ↑ Handles TLS

Die Bridge nimmt HTTPS-Requests entgegen und kommuniziert intern via Bolt mit Neo4j.

Sicherheit

Sicher wenn:

Bridge und Neo4j im gleichen Railway-Projekt
Traffic bleibt im privaten Netzwerk

Unsicher wenn:

Bridge und Neo4j auf verschiedenen Plattformen
bolt:// Traffic geht über das öffentliche Internet

Empfehlung: Immer zusammen mit Neo4j Railway im gleichen Projekt deployen.

Quick Start

Neo4j Railway deployen
Im gleichen Projekt: “New Service” → GitHub → MacStenk/neo4j-web-bridge
Via Internal URL verbinden: bolt://neo4j.railway.internal:7687

docker run -p 3000:3000 \
  -e NEO4J_URI=bolt://your-neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=your-password \
  neo4j-web-bridge

Dann http://localhost:3000 öffnen.

git clone https://github.com/MacStenk/neo4j-web-bridge.git
cd neo4j-web-bridge
npm install
npm start

Auto-Connect Modus

Für API-Nutzung und Gateway-Integration kann die Bridge automatisch beim Start verbinden.

Environment Variables setzen

NEO4J_URI=bolt://yamanote.proxy.rlwy.net:36570
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j  # optional, default: neo4j

Startup Output

╔═══════════════════════════════════════════╗
║       Neo4j Web Bridge v1.0.0             ║
╠═══════════════════════════════════════════╣
║  Server:  http://localhost:3000           ║
║  API:     http://localhost:3000/api       ║
╚═══════════════════════════════════════════╝

Auto-connect enabled. Connecting to Neo4j...
✅ Auto-connected to Neo4j: bolt://yamanote.proxy.rlwy.net:36570

Die Bridge ist sofort einsatzbereit - kein manuelles Verbinden nötig.

MCP Gateway Integration

Die Bridge funktioniert als Backend für den MCP Gateway - damit kannst du via Chat (Gemini AI) mit deiner Neo4j Datenbank sprechen.

Setup

Neo4j Web Bridge mit Auto-Connect deployen
Im MCP Gateway konfigurieren:

{
  "name": "neo4j",
  "type": "neo4j",
  "url": "https://your-neo4j-bridge.railway.app"
}

Nutzung

Im MCP Gateway Chat:

“Zeig mir alle Nodes in der Datenbank”

Der Gateway erkennt, dass er das neo4j_query Tool braucht, ruft die Bridge auf, und gibt dir die Ergebnisse zurück.

API Reference

Die Bridge bietet eine REST API - ideal für LLM-Integration und Automatisierung.

Health Check

GET /api/health

{
  "status": "ok",
  "version": "1.0.0",
  "connected": true,
  "autoConnect": true
}

Connect (Manuell)

Nur nötig wenn kein Auto-Connect konfiguriert ist.

POST /api/connect
Content-Type: application/json

{
  "uri": "bolt://neo4j.railway.internal:7687",
  "username": "neo4j",
  "password": "xxx",
  "database": "neo4j"
}

Query ausführen

POST /api/query
Content-Type: application/json

{
  "cypher": "MATCH (n) RETURN n LIMIT 10",
  "params": {}
}

Response:

{
  "success": true,
  "records": [...],
  "summary": {
    "resultConsumedAfter": 12
  }
}

Disconnect

POST /api/disconnect

LLM Integration

Die API ermöglicht direkten Neo4j-Zugriff für LLMs:

import requests

# Bei Auto-Connect: Direkt Query ausführen
response = requests.post("https://bridge.railway.app/api/query", json={
    "cypher": "MATCH (n:Person) RETURN n.name LIMIT 5"
})

print(response.json()["records"])

Anwendungsfälle:

RAG mit Knowledge Graph
Agentische Workflows mit Kontext-Speicherung
Graph-basierte Reasoning
MCP Gateway als Chat-Interface

Environment Variables

Variable	Default	Beschreibung
`PORT`	`3000`	Server Port
`NEO4J_URI`	—	Neo4j URL für Auto-Connect
`NEO4J_USER`	—	Username für Auto-Connect
`NEO4J_PASSWORD`	—	Passwort für Auto-Connect
`NEO4J_DATABASE`	`neo4j`	Database Name
`CORS_ORIGIN`	`*`	Erlaubte Origins

Architektur

┌─────────────────────────────────────────────────┐
│              Railway Private Network             │
│                                                  │
│   ┌─────────────┐         ┌─────────────────┐   │
│   │ Neo4j Web   │  bolt   │     Neo4j       │   │
│   │ Bridge      │────────▶│     Database    │   │
│   │ (Node.js)   │         │   (neo4j-railway)│   │
│   └─────────────┘         └─────────────────┘   │
│         ▲                                        │
└─────────│────────────────────────────────────────┘
          │ HTTPS (verschlüsselt)
          │
    ┌─────┴─────┐
    │  Browser  │
    │  LLM/API  │
    │  Gateway  │
    └───────────┘

Der kritische Punkt: Die bolt:// Verbindung ist unverschlüsselt, aber sie verlässt nie Railway’s privates Netzwerk.