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

2026-07-01 · Source: Towards AI - Medium · Field: Technology & Digital — Software Development & Engineering, Artificial Intelligence & Machine Learning · Depth: Intermediate, medium

Summary

The article describes how to run the Neo4j Model Context Protocol (MCP) server locally using Docker, bypassing GitHub Codespaces. It details a 30-minute, copy-paste guide to set up a Docker stack including Neo4j 5.26 and the official `neo4j-mcp` server (v1.5.2). The setup exposes Neo4j on ports 7474 (Browser) and 7687 (Bolt), and the MCP server on port 8000, configured for HTTP transport and per-request authentication. The guide covers connecting VS Code via an `.vscode/mcp.json` configuration, verifying the server with `curl` commands, and using it to interact with a local or public Neo4j database (e.g., `demo.neo4jlabs.com` on port 8001). It also includes a Python CLI example for building a real application, demonstrating how this local setup provides a controlled environment for understanding MCP's role in connecting AI agents to databases.

Key takeaway

For AI Engineers integrating agents with graph databases, self-hosting the Neo4j MCP server locally with Docker is crucial. This setup avoids cloud costs and provides direct control over authentication and transport, mirroring production deployments. You gain a deeper understanding of how agents interact with data, enabling you to implement robust security measures and troubleshoot effectively. Consider this approach to build and test agent-database connections securely.

Key insights

Self-hosting the Neo4j MCP server with Docker provides a controlled, observable environment for AI agent integration.

Principles

• MCP servers act as a bridge between AI clients and databases.
• HTTP transport with per-request auth is a production-ready model.
• Lazily registered tools require an `initialize` handshake.

Method

Set up a `docker-compose.yml` with Neo4j 5.26 and `neo4j-mcp` (v1.5.2) configured for HTTP transport on port 8000. Bring up the stack, verify with `curl`, then connect VS Code using an `http` type `mcp.json` config.

In practice

• Run `neo4j-mcp` as a standalone HTTP service.
• Use `curl` to test MCP endpoint authentication.
• Configure VS Code `mcp.json` for `http` type server.

Topics

• Neo4j
• Docker Compose
• Model Context Protocol
• Graph Databases
• VS Code Integration
• AI Agents

Code references

• neo4j/mcp
• neo4j/mcp

Best for: AI Engineer, Machine Learning Engineer, Software Engineer

Related on AIssential

• Google Brings MCP Support to Colab, Enabling Cloud Execution for AI Agents — The Colab MCP Server enables AI agents to programmatically control Google Colab for cloud-based task execution.
• My AI Couldn’t See My Files — I Built a Zero-Dependency MCP Server — Building simple tools with standard libraries avoids unnecessary complexity and improves real-world reliability.
• Self-Hosted AI: A Complete Roadmap for Beginners — Build a private AI automation hub using Docker, Ollama, and n8n for local, cloud-independent workflows.
• Exclusive: LucidLink launches MCP server to give AI agents shared access to distributed files — LucidLink's MCP server provides shared, persistent file access for multi-agent AI systems across distributed environments, solving context and data movement issues.
• Run custom MCP proxies serverless on Amazon Bedrock AgentCore Runtime — Deploying a serverless MCP proxy on AgentCore Runtime enables custom governance and control over AI agent-tool interactions.
• The Container Is the Agent: Why Docker and MCP Are Quietly Building the Backbone of Production AI — Production AI agent success hinges on robust infrastructure, not just model capabilities, with containerization offering key reproducibility and security.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Towards AI - Medium.