# neo4j-contrib/mcp-neo4j architecture

> Architecture diagram of the GitHub repository neo4j-contrib/mcp-neo4j, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neo4j-contrib/mcp-neo4j
- Repository: https://github.com/neo4j-contrib/mcp-neo4j

## Overview

##### Project Type and Purpose
- The project implements the Model Context Protocol (MCP) – a standardized protocol for enabling natural language interactions with Neo4j through multiple server implementations.
- Its purpose is to translate natural language requests (from MCP clients like Claude Desktop) into operations such as converting natural language to Cypher queries, or managing memory (knowledge graph memory) using either Neo4j as a storage backend or a JSON file.

##### Analyzing the File Structure
- The top-level structure includes configuration and build files (e.g., .editorconfig, .prettierrc, nx.json) as well as multiple directories:
- The “libs” directory includes a “graphrag-memory” library – likely a helper library shared across components.
- The “servers” directory contains several subdirectories:
▪ mcp-json-memory – a Node/TypeScript based server handling memory in a file.
▪ mcp-neo4j-cypher – a Python based server converting natural language into Cypher queries.
▪ mcp-neo4j-memory – a Python based server managing memory in Neo4j.
▪ mcp-neo4j-cloud-aura-api – (even if not mentioned in the README servers list, it appears integrated) a Python based server likely intended for managing Aura account interactions.
- There are corresponding configuration and test files in each server directory which indicate modular, self-contained projects.

##### Insights from the README
- The README is concise and clearly lists three main server functionalities: natural language to Cypher queries, and memory management via both Neo4j and JSON file storage.
- It frames the project as one that leverages external client connections (e.g., Claude Desktop using MCP Client) and clearly delineates each server’s role.

a. Main Components:
- MCP Clients: External clients (e.g., Claude Desktop) that send natural language requests.
- Servers:
▪ mcp-neo4j-cypher: Converts natural language to Cypher queries.
▪ mcp-neo4j-memory: Uses Neo4j to store the knowledge graph memory.
▪ mcp-json-memory: Uses local file (JSON) storage for memory.
▪ mcp-neo4j-cloud-aura-api: Connects to Neo4j Aura for cloud-based interactions.
- Shared Libraries: For example, “graphrag-memory” providing core memory functionality.
- External Systems: Neo4j databases (both self-hosted and Aura cloud) and possibly file storage systems.

b. Relationships and Interactions:
- Each server might interact with its configured data store (Neo4j database for “mcp-neo4j-memory” and “mcp-neo4j-cypher”, JSON file system for “mcp-json-memory”).
- The shared “graphrag-memory” library (in the libs directory) is used by one or more servers to implement common memory operations.
- Optionally, show how “mcp-neo4j-cloud-aura-api” integrates with Neo4j Aura (cloud service) representing external dependency.

c. Important Architectural Patterns and Design Principles:
- Clearly separated concerns: each server is focused on one specific use case.
- Modular design: Using independent servers and a shared library to promote code reuse and maintainability.
- Protocol-based communication: Each server is built to adhere to the standard MCP, ensuring a unified client interface.

d. Relevant Technologies, Frameworks, and Libraries:
- Node.js/TypeScript (for mcp-json-memory) – indicated by files like main.ts, eslint.config.js, jest.config.ts.
- Python (for mcp-neo4j-cypher, mcp-neo4j-memory, mcp-neo4j-cloud-aura-api) – indicated by pyproject.toml, server.py, tests.
- Neo4j database: for storing graph data and executing Cypher queries.
- Shared libraries: “graphrag-memory” which contains its own testing and configuration setup.
- CI/CD GitHub workflows indicate automated testing and publishing.

##### Specific Elements
- Clear Labels: Each component (servers, library, clients, external systems) should be distinctly labeled.
- Client requests → to specific MCP servers.
- Server responses → back to clients.
- Data flows from servers to the external data stores (Neo4j, JSON files).
- Interactions from servers to the shared library.
- Separate visual style for external dependencies (Neo4j database/cloud services).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Clients
    subgraph "Clients"
        C["MCP Clients"]:::client
    end

    %% Servers
    subgraph "Servers"
        S1["mcp-json-memory Server"]:::nodejs
        S2["mcp-neo4j-cypher Server"]:::python
        S3["mcp-neo4j-memory Server"]:::python
        S4["mcp-neo4j-cloud-aura-api Server"]:::python
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        L["graphrag-memory Library"]:::library
    end

    %% External Systems
    subgraph "External Systems"
        E1["Neo4j Database"]:::external
        E2["File Storage (JSON)"]:::external
        E3["Neo4j Aura"]:::external
    end

    %% Client to Servers Requests
    C -->|"sendsRequest"| S1
    C -->|"sendsRequest"| S2
    C -->|"sendsRequest"| S3
    C -->|"sendsRequest"| S4

    %% Servers Responses to Clients
    S1 -->|"sendsResponse"| C
    S2 -->|"sendsResponse"| C
    S3 -->|"sendsResponse"| C
    S4 -->|"sendsResponse"| C

    %% Servers accessing External Systems
    S1 -->|"accesses"| E2
    S2 -->|"queries"| E1
    S3 -->|"accesses"| E1
    S4 -->|"connects"| E3

    %% Servers utilizing Shared Library
    S1 -->|"uses"| L
    S2 -->|"uses"| L
    S3 -->|"uses"| L
    S4 -->|"uses"| L

    %% Click Events
    click S1 "https://github.com/neo4j-contrib/mcp-neo4j/blob/main/servers/mcp-json-memory/src/main.ts"
    click S2 "https://github.com/neo4j-contrib/mcp-neo4j/blob/main/servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/server.py"
    click S3 "https://github.com/neo4j-contrib/mcp-neo4j/blob/main/servers/mcp-neo4j-memory/src/mcp_neo4j_memory/server.py"
    click S4 "https://github.com/neo4j-contrib/mcp-neo4j/blob/main/servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/server.py"
    click L "https://github.com/neo4j-contrib/mcp-neo4j/blob/main/libs/graphrag-memory/src/lib/graphrag-memory.ts"

%% Styles
classDef client fill:#FFB6C1,stroke:#000,stroke-width:2px;
classDef nodejs fill:#FFA07A,stroke:#000,stroke-width:2px;
classDef python fill:#87CEFA,stroke:#000,stroke-width:2px;
classDef library fill:#FFD700,stroke:#000,stroke-width:2px;
classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
```
