Neo4j MCP Server Connected to ChatGPT

This walkthrough rebuilds the path from raw materials to a working system for: How to Build and Connect a Neo4j MCP Server to ChatGPT. The focus is operable steps, explicit checks, and code that you can drop into a repo without guessing intent. For Overview, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

Introduction

For Introduction, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms.

Neo4j Labs Repository Versus the Official Neo4j MCP Server

For Neo4j Labs Repository Versus the Official Neo4j MCP Server, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms.

Architecture

For Architecture, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms. For Architecture, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

Prerequisites

For Prerequisites, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests.

Step 1: Verify the Ubuntu Architecture

For Step 1: Verify the Ubuntu Architecture, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests.

Step 2: Install the Official Neo4j MCP Server

For Step 2: Install the Official Neo4j MCP Server, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests. For Step 2: Install the Official Neo4j MCP Server, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

tar -xzf neo4j-mcp_Linux_x86_64.tar.gz
chmod +x neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/neo4j-mcp

neo4j-mcp --help

python3 -m venv neo4j-mcp-venv
source neo4j-mcp-venv/bin/activate
pip install neo4j-mcp-server

Step 3: Understand the Available MCP Tools

For Step 3: Understand the Available MCP Tools, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Model nodes and relationships for the questions you will ask, not for every noun in the document. Sparse, typed edges beat dense mystery graphs.

Step 4: Create a Restricted Neo4j User

For Step 4: Create a Restricted Neo4j User, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Model nodes and relationships for the questions you will ask, not for every noun in the document. Sparse, typed edges beat dense mystery graphs.

cypher-shell \
  -a bolt://127.0.0.1:7687 \
  -u mcp_reader \
  -p 'YOUR_PASSWORD' \
  'MATCH (n) RETURN count(n) AS node_count;'

Step 5: Configure Neo4j MCP in STDIO Mode

For Step 5: Configure Neo4j MCP in STDIO Mode, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Model nodes and relationships for the questions you will ask, not for every noun in the document. Sparse, typed edges beat dense mystery graphs. For Step 5: Configure Neo4j MCP in STDIO Mode, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

export NEO4J_URI="bolt://127.0.0.1:7687"
export NEO4J_USERNAME="mcp_reader"
export NEO4J_PASSWORD="YOUR_NEO4J_PASSWORD"
export NEO4J_DATABASE="neo4j"
export NEO4J_READ_ONLY="true"
export NEO4J_TRANSPORT_MODE="stdio"
export NEO4J_LOG_LEVEL="info"
export NEO4J_LOG_FORMAT="text"

neo4j-mcp

Step 6: Understand the HTTP Alternative

For Step 6: Understand the HTTP Alternative, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms.

export NEO4J_URI="bolt://127.0.0.1:7687"
export NEO4J_DATABASE="neo4j"
export NEO4J_READ_ONLY="true"
export NEO4J_TRANSPORT_MODE="http"
export NEO4J_MCP_HTTP_HOST="127.0.0.1"
export NEO4J_MCP_HTTP_PORT="8000"

unset NEO4J_USERNAME
unset NEO4J_PASSWORD

neo4j-mcp

Authorization: Basic BASE64_ENCODED_USERNAME_AND_PASSWORD

echo -n "mcp_reader:YOUR_PASSWORD" | base64

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN

Step 7: Install OpenAI tunnel-client on Ubuntu

For Step 7: Install OpenAI tunnel-client on Ubuntu, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms.

tunnel-client-<version>-linux-amd64.zip

tunnel-client-<version>-linux-arm64.zip

unzip tunnel-client-<version>-linux-amd64.zip
chmod +x tunnel-client
sudo mv tunnel-client /usr/local/bin/tunnel-client

tunnel-client --version
tunnel-client help quickstart

Step 8: Create the Secure MCP Tunnel

For Step 8: Create the Secure MCP Tunnel, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Use constraints and indexes before bulk ingest. Uniqueness on business keys turns later merges into predictable upserts instead of duplicate storms. For Step 8: Create the Secure MCP Tunnel, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

Name: Neo4jMCP
Description: Private tunnel for the Neo4j MCP server

tunnel_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 9: Create the Runtime API Key

For Step 9: Create the Runtime API Key, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests.

export CONTROL_PLANE_API_KEY="sk-YOUR_RUNTIME_KEY"

Step 10: Configure tunnel-client to Launch Neo4j MCP

For Step 10: Configure tunnel-client to Launch Neo4j MCP, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests.

export CONTROL_PLANE_API_KEY="sk-YOUR_RUNTIME_KEY"
export NEO4J_URI="bolt://127.0.0.1:7687"
export NEO4J_USERNAME="mcp_reader"
export NEO4J_PASSWORD="YOUR_NEO4J_PASSWORD"
export NEO4J_DATABASE="neo4j"
export NEO4J_READ_ONLY="true"
export NEO4J_TRANSPORT_MODE="stdio"

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile neo4j-local \
  --tunnel-id "tunnel_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --mcp-command "/usr/local/bin/neo4j-mcp"

tunnel-client doctor \
  --profile neo4j-local \
  --explain

tunnel-client run --profile neo4j-local

Step 11: Verify Ubuntu Network Connectivity

For Step 11: Verify Ubuntu Network Connectivity, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests. For Step 11: Verify Ubuntu Network Connectivity, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

curl -I https://api.openai.com

Step 12: Create the ChatGPT Developer-Mode App

For Step 12: Create the ChatGPT Developer-Mode App, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Model nodes and relationships for the questions you will ask, not for every noun in the document. Sparse, typed edges beat dense mystery graphs.

Step 13: Validate the Integration

For Step 13: Validate the Integration, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Model nodes and relationships for the questions you will ask, not for every noun in the document. Sparse, typed edges beat dense mystery graphs.

Operational checklist

For Operational checklist, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state.

Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Inspect a sample neighborhood after the first batch. Cypher probes catch label drift and missing properties cheaper than end-to-end chat tests.

Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.

Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.