Home / Articles

Run the Neo4j MCP Server on Your Own Machine with Docker and VS Code

Self-host Neo4j and its official MCP server with Docker Compose, secure it with Basic Auth over HTTP, connect VS Code in Agent mode and query a demo graph.

Publisher: REACTAPP.TOP8 min read1743 words

This article is published in English.

Sources: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)

Neo4j's official MCP server is a small program, and the whole stack can run on a laptop with Docker in roughly half an hour. That matters for anyone following the GraphAcademy course on developing with Neo4j MCP tools, because the course assumes GitHub Codespaces, and Codespaces has a monthly free allowance that eventually runs out. Self-hosting removes the limit and costs nothing. The steps below were run end to end, and they also show how the pieces of MCP fit together.

What gets built

VS Code (host)  ──HTTP /mcp + auth──►  neo4j-mcp (server)  ──Bolt──►  Neo4j (database)

Three separate parts make up the setup, and seeing the split clearly does most of the work.

  • Host: the MCP client, for example VS Code, Claude Desktop or Cursor. It handles the MCP protocol and has no idea Neo4j exists.
  • MCP server: the neo4j-mcp bridge, which translates MCP tool calls such as read-cypher into real Bolt queries.
  • Database: Neo4j itself.

A frequent misunderstanding is that some remote "MCP database" lives in the cloud. It doesn't. The MCP server is a program that gets run locally, and it connects outward to whichever database it is pointed at.

Prerequisites

Docker Desktop must be installed and running, which docker --version confirms. VS Code with MCP support is needed, plus a terminal. Python and a Neo4j install are not required, since Docker covers both.

Step 1: Write the Docker stack

Create a project folder and put a docker-compose.yml in it. The file defines two services. First comes the database:

services:
  neo4j:
    image: neo4j:5.26
    container_name: neo4j
    ports:
      - "7474:7474"          # Neo4j Browser  -> http://localhost:7474
      - "7687:7687"          # Bolt
    environment:
      NEO4J_AUTH: "neo4j/password123"
      NEO4J_PLUGINS: '["apoc","graph-data-science"]'   # needed for get-schema + GDS tool
    volumes:
      - neo4j_data:/data
    healthcheck:
      test: ["CMD-SHELL", "cypher-shell -u neo4j -p password123 'RETURN 1' || exit 1"]
      interval: 10s
      timeout: 10s
      retries: 12
      start_period: 30s

Second comes the MCP server, built straight from the official repository at a pinned tag:

  neo4j-mcp:
    build:
      context: "https://github.com/neo4j/mcp.git#v1.5.2"   # builds the official server from source
    container_name: neo4j-mcp
    depends_on:
      neo4j:
        condition: service_healthy
    ports:
      - "8000:8000"          # MCP endpoint -> http://localhost:8000/mcp
    environment:
      NEO4J_URI: "bolt://neo4j:7687"
      NEO4J_DATABASE: "neo4j"
      NEO4J_TRANSPORT_MODE: "http"     # networked service, not a stdio subprocess
      NEO4J_MCP_HTTP_HOST: "0.0.0.0"   # bind all interfaces so the host can reach it
      NEO4J_MCP_HTTP_PORT: "8000"      # must be >1024 (container runs as non-root)volumes:
  neo4j_data:

Two details here deserve attention.

  • HTTP transport instead of stdio. The course starts the server in stdio mode, where the host launches it as a child process. This stack runs it as a standalone HTTP service, which is closer to a real deployment and lets any client connect by URL.
  • Why those values. The container is not root, so binding a privileged port under 1024 fails. Port 8000 stands in for 80 for that reason. In HTTP mode the server also refuses NEO4J_USERNAME and NEO4J_PASSWORD environment variables by design. Credentials arrive with each request through HTTP Basic Auth, which matches the production auth model, so those variables stay out.

Step 2: Start it

docker compose up -d --build

The first run pulls the Neo4j image, compiles the Go MCP server and downloads the APOC and GDS plugins. After about a minute, check that both containers are up:

docker compose ps

Wait for neo4j to report (healthy).

Step 3: Verify the server

The MCP endpoint lives at http://localhost:8000/mcp. Opening it in a browser returns Method Not Allowed: only POST is supported. That is actually reassuring, because it means the server is alive and the browser simply sent a GET.

Use curl for a proper test. Begin by confirming that authentication is enforced:

curl -i -X POST http://localhost:8000/mcp        # expect 401 Unauthorized

Next, list the tools while authenticating with the database credentials:

curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:8000/mcp

The response should name get-schema, read-cypher and write-cypher.

Why only three tools show up

The course describes four tools, and the missing one is list-gds-procedures. Nothing is broken. That tool is registered lazily during the MCP initialize handshake, and only when Graph Data Science is installed. A bare tools/list request skips the handshake, so the fourth tool never appears. Send initialize first and then list again:

curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}},"id":1}' \
  http://localhost:8000/mcp
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}' \
  http://localhost:8000/mcp

All four tools appear now. Real clients like VS Code run initialize on their own, so this quirk only affects raw curl calls.

Step 4: Connect VS Code

Create .vscode/mcp.json in the project:

{
    "servers": {
        "neo4j": {
            "type": "http",
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
            }
        }
    }
}

The Authorization value is just the base64 encoding of neo4j:password123. After a password change, regenerate it with:

printf 'neo4j:yourpassword' | base64

The most common mistake is reusing the course's stdio configuration ("type": "stdio", "command": "neo4j-mcp") against this Docker setup. That tells VS Code to launch a local binary that doesn't exist. A containerized server needs the http config shown above.

In VS Code, open the command palette with Cmd/Ctrl + Shift + P, run MCP: List Servers, pick neo4j and choose Start Server. Next switch Chat to Agent mode (Cmd/Ctrl + Shift + I) and request a list of the available MCP tools with IDs and descriptions. Four tools are returned.

Step 5: Put it to use

The local database starts out empty, so a second, disposable MCP container can point at Neo4j's public movies demo database, the same one the course uses, on a different port. The main stack stays untouched:

docker run --rm -d --name mcp-movies \
  -e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
  -e NEO4J_DATABASE="recommendations" \
  -e NEO4J_TRANSPORT_MODE="http" \
  -e NEO4J_MCP_HTTP_HOST="0.0.0.0" \
  -e NEO4J_MCP_HTTP_PORT="8001" \
  -p 8001:8001 \
  <your-project-name>-neo4j-mcp

The image name is whatever docker compose built. Run docker images to see it, and expect something like yourfolder-neo4j-mcp.

To read the schema and see which relationships a User has, call read-cypher:

curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (u:User)-[r]->() RETURN DISTINCT type(r) AS rel"}},"id":2}' \
  http://localhost:8001/mcp

The answer is RATED, meaning (:User)-[:RATED]->(:Movie).

To generate a query for the highest-rated movie, include a non-null guard, because not every movie carries a rating:

curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (m:Movie) WHERE m.imdbRating IS NOT NULL RETURN m.title AS title, m.imdbRating AS rating ORDER BY m.imdbRating DESC LIMIT 1"}},"id":3}' \
  http://localhost:8001/mcp

When the demo is finished, stop the container:

docker stop mcp-movies

Step 6: A small app on top

The course ends by having learners vibe-code a Python command-line tool that returns the top five movies in a genre. This lean version passes the genre as a query parameter, never by string concatenation, and filters out null ratings:

import os, sys
from neo4j import GraphDatabase
QUERY = """
MATCH (m:Movie)-[:IN_GENRE]->(:Genre {name: $genre})
WHERE m.imdbRating IS NOT NULL
RETURN m.title AS title, m.imdbRating AS rating
ORDER BY m.imdbRating DESC
LIMIT 5
"""def main():
    uri = os.environ["NEO4J_URI"]
    user = os.environ["NEO4J_USERNAME"]
    pwd = os.environ["NEO4J_PASSWORD"]
    db = os.environ.get("NEO4J_DATABASE", "neo4j")    genre = input("Enter a movie genre: ").strip()
    with GraphDatabase.driver(uri, auth=(user, pwd)) as driver:
        driver.verify_connectivity()
        records, _, _ = driver.execute_query(QUERY, genre=genre, database_=db)    print(f"\nTop {len(records)} '{genre}' movies:")
    for i, r in enumerate(records, 1):
        print(f"  {i}. {r['title']} ({r['rating']})")if __name__ == "__main__":
    main()

Run it against the demo database:

pip install neo4j
export NEO4J_URI="neo4j+s://demo.neo4jlabs.com"
export NEO4J_USERNAME="recommendations"
export NEO4J_PASSWORD="recommendations"
export NEO4J_DATABASE="recommendations"
python3 movie_recommender.py      # then type: Mystery

What was accomplished

In about half an hour the full Neo4j MCP stack runs locally with no Codespaces and no cloud bill:

  • Neo4j with APOC and GDS, plus the official neo4j-mcp server, both in Docker
  • The MCP server as an authenticated HTTP service
  • VS Code connected in Agent mode
  • Real queries through the MCP tools and a small Python app on top

Why self-hosting teaches more

It would be easy to read this as a way around a quota, but running the server personally shows something more useful. MCP is turning into the standard route for AI agents to reach real systems: databases, APIs and internal tools. The interesting engineering questions sit exactly where this setup ends up. How does the server get transported? How are requests authenticated? What prevents an agent from running a destructive query?

Operating the server over HTTP, with per-request auth and a read-only switch, brings those questions to the surface, whereas a prebuilt hosted sandbox buries them. With agents increasingly fronting live production data, running an MCP server as a controlled, observable service matters more than trusting a black box somebody else hosts. The same layout carries over to a real deployment behind a gateway with TLS and a secrets manager.

Troubleshooting

  • Method Not Allowed in the browser: the request was a GET and the endpoint only takes POST. Use curl or an MCP client.
  • 401 Unauthorized: Basic Auth is missing or wrong. Use the database username and password.
  • Only three tools listed: send initialize first, and make sure APOC and GDS are installed.
  • get-schema fails: APOC isn't installed. Add it to NEO4J_PLUGINS.
  • Server refuses to start and complains about credentials: NEO4J_USERNAME or NEO4J_PASSWORD was set in HTTP mode. Remove both.
  • VS Code says the server "requires interaction to start": mcp.json still holds the stdio config. Switch to the http one.
  • Permission denied when binding the port: keep NEO4J_MCP_HTTP_PORT above 1024, since the container isn't root.

Further reading

The Neo4j MCP server docs and the official MCP specification cover the details.