mcp-neo4j

The mcp-neo4j MCP server family provides a collection of neural-language driven interfaces that let you work with Neo4j data through natural language. The umbrella server supports multiple transport modes (STDIO by default, SSE, and HTTP) so you can use local tooling or deploy to web-ready environments. Common capabilities include generating Cypher queries from natural language (via the mcp-neo4j-cypher sub-server), storing and querying personal knowledge graphs in Neo4j (mcp-neo4j-memory), managing Neo4j Aura cloud instances (mcp-neo4j-cloud-aura-api), and interactive graph data modeling and visualization (mcp-neo4j-data-modeling). You can run these servers in HTTP mode by supplying the appropriate transport flags and environment variables to expose a REST-like interface for MCP clients such as Claude Desktop, VS Code, or other MCP clients.

To use HTTP transport, start the server with the HTTP flag and configure host, port, and path. Example settings shown in the repository include host 127.0.0.1, port 8080, and API path /api/mcp/. You can also rely on environment variables to configure transport at runtime, for example NEO4J_TRANSPORT, NEO4J_MCP_SERVER_HOST, NEO4J_MCP_SERVER_PORT, and NEO4J_MCP_SERVER_PATH. Once running, you can query the graph, inspect schemas (with APOC-enabled Neo4j for schema introspection in the Cypher interface), and perform operations such as creating and managing Aura instances or modeling graphs via the data modeling toolset.

If you’re integrating with an MCP client, point it at the server’s HTTP endpoint (host, port, and path as configured) and send natural language prompts. The system will translate those prompts into Cypher or data-modeling operations, returning results that your client can present to the user.

Prerequisites

• Docker or a compatible container runtime (recommended for cloud deployment)
• Access to a Neo4j instance (local, remote, or Neo4j Aura) with appropriate credentials
• APOC plugin installed and enabled on the Neo4j instance when using the Cypher/NLP-to-Cypher capabilities
• Optional: environment for HTTP transport if deploying behind a reverse proxy or in production

Installation steps (Docker-based deployment)

1. Ensure Docker is installed and running on your machine.

2. Pull and run the MCP server image (example image name placeholder; replace with the actual image name from your release channel):

   docker pull your-org/mcp-neo4j:latest

   docker run -it --rm
   -p 8080:8080
   -e NEO4J_TRANSPORT=http
   -e NEO4J_MCP_SERVER_HOST=0.0.0.0
   -e NEO4J_MCP_SERVER_PORT=8080
   -e NEO4J_MCP_SERVER_PATH=/api/mcp/
   -e NEO4J_AURA_ACCESS_TOKEN=YOUR_AURA_TOKEN
   your-org/mcp-neo4j:latest

   Notes:

   • Adjust the host/port/path as needed for your environment.
   • If you’re not using HTTP, you can run in STDIO mode by omitting the HTTP environment variables and not mapping port 8080.

3. Verify the server starts and is reachable:

   curl http://127.0.0.1:8080/api/mcp/health || echo 'health check failed'

Alternative: Local/Manual deployment without Docker

• If you have a direct build or an installation script provided by the project, follow its instructions to install the binary at your system path and then start it with the desired transport and host/port options as shown in the HTTP transport examples in the repository README.

Prerequisites recap

• Docker (recommended) or a compatible runtime
• Neo4j instance (local/remote) with APOC for schema operations when using Cypher-based features
• Access tokens or credentials for Neo4j Aura if targeting Aura environments
• Familiarity with environment variable configuration for transport and server details

Tips and common issues:

• If you enable HTTP transport, ensure your host/port are not blocked by firewalls and that the path matches what your MCP client expects.
• For Cypher schema inspection, APOC must be installed and enabled on the target Neo4j instance.
• When deploying to production, consider using the HTTP transport in combination with a reverse proxy and proper TLS termination.
• The repository emphasizes that Neo4j Labs MCP servers are experimental and may change without backward compatibility guarantees; plan accordingly for stability.
• If you encounter authentication or connectivity issues to Neo4j or Aura, verify network access, credentials, and that the correct API endpoints are reachable from the MCP server container.
• For cloud deployment, the companion cloud deployment guide (linked in the README) contains step-by-step instructions for AWS ECS Fargate and Azure Container Apps, including auto-scaling and load balancing considerations.