NE
OfficialDeveloper Tools

Neo4j GDS MCP Server for Graph Algorithms

Analyze complex networks with the Neo4j GDS MCP server using comprehensive graph algorithms for advanced reasoning and Q&A.

View on GitHub

Overview

The Neo4j GDS MCP Server exposes Neo4j Graph Data Science (GDS) capabilities through a Model Context Protocol (MCP) compatible server so language models and agent frameworks can call graph algorithms as tools. By wrapping GDS algorithms in a simple HTTP/MCP tool interface, the server enables advanced graph reasoning, retrieval-augmented Q&A, and explainable results directly from a Neo4j graph database.

This is useful when you want to augment an LLM with structured graph reasoning: use centrality and community detection for entity ranking, shortest-paths and subgraph extraction for evidence chains, and similarity algorithms for recommendation or entity linking. The server is intended for developers integrating graph analytics into AI agents, chains, and automated workflows.

Features

  • Exposes common Neo4j GDS algorithms (PageRank, community detection, shortest path, node similarity, embeddings) as callable tools
  • MCP-compatible interface so LLMs and orchestration frameworks can invoke graph operations
  • Configurable Neo4j connection (database, host, credentials) via environment variables
  • Returns algorithm outputs as structured JSON suitable for LLM consumption and downstream tooling
  • Supports subgraph extraction and lightweight explainability (top-K contributing nodes/edges)
  • Runs as a standalone FastAPI/uvicorn server (Docker-friendly)

Installation / Configuration

  1. Clone the repository and create a virtual environment:
git clone https://github.com/neo4j-contrib/gds-agent.git
cd gds-agent
python -m venv .venv
source .venv/bin/activate
  1. Install dependencies:
pip install -r requirements.txt
# or install the package in editable mode
pip install -e .
  1. Configure environment variables for Neo4j and server options:
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your-password"
export GDS_DATABASE="neo4j"      # target database for GDS operations
export MCP_HOST="0.0.0.0"
export MCP_PORT="8080"
  1. Start the server (example using uvicorn):
uvicorn gds_agent.server:app --host ${MCP_HOST} --port ${MCP_PORT} --reload

Or run via Docker (example Dockerfile or image may be provided in the repo):

docker build -t neo4j-gds-mcp .
docker run -e NEO4J_URI -e NEO4J_USER -e NEO4J_PASSWORD -p 8080:8080 neo4j-gds-mcp

Available Tools / Resources

The server exposes a set of graph-algorithm tools. Typical endpoints and resources (HTTP JSON) you can expect:

  • GET /algorithms
    • Returns a list of available algorithms and their parameters
  • POST /run
    • Run an algorithm:
      • body: { “algorithm”: “pagerank”, “graph”: “myGraph”, “params”: { … } }
  • GET /graphs
    • List graphs available in GDS catalog
  • POST /subgraph
    • Extract a subgraph for a set of nodes for evidence and context
  • POST /explain
    • Return top-K contributors for a result (e.g., top influencing nodes for PageRank)

Example “run” request:

curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "pagerank",
    "graph": "myGraph",
    "params": { "maxIterations": 20, "dampingFactor": 0.85, "topK": 10 }
  }'

Response: structured JSON with ranked nodes, scores, and optional subgraph evidence.

Use Cases

  • Influencer detection in social networks

    • Run PageRank on a social graph to identify high-impact accounts. Return top-K nodes and a subgraph of their 1-hop neighborhoods to be used as evidence in an LLM response.

  • Community detection for topic clustering

    • Use Louvain or label propagation to group related entities (products, authors, customers). Feed cluster labels back into your application for targeted recommendations or summarization.

  • Explainable Q&A and reasoning chains

    • For a question like “How are product A and B related?”, compute shortest paths and extract the connecting subgraph. Return node/edge sequences as an evidence chain the LLM can reference.

  • Recommendation and similarity search

    • Run node similarity or embedding-based nearest neighbors to provide personalized recommendations or to expand context when answering an LLM query.

  • Graph-based retrieval for RAG (Retrieval-Augmented Generation)

    • Extract a focused subgraph around query-relevant entities and pass structured facts to the model to improve factuality and traceability.

Tips for Developers

  • Keep the graph used for GDS (named graph/catalyst graph) reasonably sized for the algorithms you intend to run; some algorithms are memory sensitive.
  • Use the server’s explain/subgraph endpoints to produce concise evidence for LLM responses rather than sending raw graph dumps.
  • Combine algorithm outputs with provenance (timestamps, relationship types) to improve trustworthiness in an LLM-driven workflow.

For full implementation details, algorithm-specific parameters, and Docker examples, see the project README and source in the repository: https://github.com/neo4j-contrib/gds-agent.

Tags:developer-tools