mcp-graph-engine 0.1.2

A graph database and analysis tool for AI assistants via MCP

MCP Graph Engine

A graph database and analysis tool that plugs into AI assistants via the Model Context Protocol (MCP). Build relationship graphs, run analysis algorithms, and visualise everything in real-time.

What's This For?

You know how you're debugging something gnarly and you end up with a whiteboard full of boxes and arrows? Or you're trying to understand a codebase and the dependencies are doing your head in? This is that whiteboard, except your AI assistant can build it, query it, and run proper graph algorithms on it.

Some things it's good for:

• Mapping code dependencies and finding circular imports
• Building knowledge graphs while researching a topic
• Tracing request flows through a system
• Debugging complex issues (symptoms, causes, evidence)
• Understanding relationships in any domain

The key bit: your AI assistant builds the graph as you work together, then you can both reason about it. The live visualisation means you can see what's being built in real-time.

Quick Demo

You: "Map out the auth system dependencies"

Claude: *adds nodes for AuthService, UserRepository, TokenValidator, Database*
        *adds edges showing what depends on what*

You: "What's the most critical component?"

Claude: *runs PageRank* "Database has the highest centrality -
         everything flows through it eventually"

You: "Any circular dependencies?"

Claude: *runs cycle detection* "Yeah, AuthService and TokenValidator
         have a circular dep through SessionManager"

Meanwhile, you're watching the graph build in your browser at http://localhost:8765.

Installation

Requirements: Python 3.10+ and an MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.)

1. Install the package

pipx install mcp-graph-engine

That's it. pipx installs the tool in an isolated environment and adds it to your PATH.

Optional: Enable semantic matching with embeddings

The default install uses exact and normalised string matching for node lookups. For semantic/fuzzy matching (e.g., "auth service" matching "AuthService"), install with embeddings support:

pipx install mcp-graph-engine[embeddings]

This adds sentence-transformers (PyTorch-based) which increases install size but enables smarter node matching.

Alternative installation methods

# Using uv (fast Python package manager)
uv tool install mcp-graph-engine

# Using pip (may require manual PATH setup)
pip install mcp-graph-engine

# With embeddings support
pip install mcp-graph-engine[embeddings]

# From source
git clone https://github.com/utilitydelta/mcp-graph-engine.git
cd mcp-graph-engine
pip install -e .

2. Add to your MCP client

Add this to your MCP configuration file:

{
  "mcpServers": {
    "graph-engine": {
      "command": "mcp-graph-engine"
    }
  }
}

Where's the config file?

Client	Location
Claude Code	~/.mcp.json (global) or .mcp.json (project)
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor	.cursor/mcp.json

3. Restart your client

Restart Claude Code / Claude Desktop / Cursor. The graph tools should now be available - ask your assistant to list its tools to verify.

Usage

Adding Data

The easiest way is the knowledge DSL - just plain text relationships:

Alice knows Bob
Bob works_at TechCorp
TechCorp located_in Sydney

Or with type hints:

AuthService:service depends_on UserRepository:repository
UserRepository:repository queries Database:infrastructure

You can also use structured facts if you need more control:

{
  "facts": [
    {"from": "AuthService", "to": "Database", "rel": "depends_on", "from_type": "service"}
  ]
}

Querying

Natural language patterns (via ask_graph):

• "what depends on Database"
• "what does AuthService depend on"
• "path from Frontend to Database"
• "find cycles"
• "most connected nodes"

Cypher queries for the fancy stuff:

MATCH (s:service)-[r]->(d)
WHERE r.relation = "depends_on"
RETURN s.label, d.label

Analysis Tools

Tool	What It Does
shortest_path	Find the shortest route between two nodes
all_paths	Find every possible path (careful with large graphs)
pagerank	Identify the most important/central nodes
find_cycles	Detect circular dependencies
connected_components	Find clusters of related nodes
degree_centrality	See which nodes have the most connections
transitive_reduction	Clean up redundant edges

Visualisation

visualize_graph(graph="my-graph")

Opens http://localhost:8765/graphs/my-graph in your browser. It's a D3 force-directed graph that updates in real-time as nodes and edges are added.

You can filter the visualisation with Cypher:

update_visualization_filter(filter='MATCH (n)-[r]->(m) WHERE n.type = "service" RETURN n,r,m')

Import/Export

Supported formats: DOT, CSV, GraphML, JSON, Mermaid

# Export to Mermaid for documentation
export_graph(format="mermaid")

# Import an existing DOT file
import_graph(format="dot", file_path="/path/to/deps.dot")

Full Tool Reference

Graph Management

Tool	Description
add_facts	Add relationships (auto-creates nodes)
add_knowledge	Add relationships using simple DSL
list_graphs	List all named graphs
delete_graph	Delete a graph
get_graph_info	Get stats (node count, edge count, density, etc.)

Querying

Tool	Description
ask_graph	Natural language queries for common patterns
cypher_query	Full Cypher query support
dump_context	Get a complete summary of the graph state

Analysis

Tool	Description
shortest_path	Dijkstra's shortest path
all_paths	All simple paths between nodes
pagerank	PageRank centrality scores
find_cycles	Cycle detection
connected_components	Find clusters
degree_centrality	In/out degree analysis
transitive_reduction	Remove redundant edges
subgraph	Extract a subset of nodes

Node/Edge Operations

Tool	Description
forget	Remove a node (and its edges)
forget_relationship	Remove an edge

Import/Export

Tool	Description
import_graph	Import from DOT, CSV, GraphML, JSON
export_graph	Export to DOT, CSV, GraphML, JSON, Mermaid
create_from_mermaid	Create graph from Mermaid syntax

Visualisation

Tool	Description
visualize_graph	Open browser visualisation
update_visualization_filter	Apply Cypher filter to the view
stop_visualization	Stop the visualisation server

Configuration

Environment variables:

Variable	Default	Description
VIS_ENABLED	true	Enable/disable visualisation server
VIS_PORT	8765	Port for the visualisation server
VIS_HOST	localhost	Host to bind the visualisation server

Architecture

src/mcp_graph_engine/
├── server.py           # MCP server, tool handlers
├── graph_engine.py     # NetworkX wrapper, algorithms
├── session.py          # Named graph sessions
├── matcher.py          # Fuzzy matching (exact, normalised, embeddings)
├── cypher.py           # Cypher query execution
└── visualization/
    ├── web_server.py   # FastAPI + WebSocket server
    └── broadcast.py    # Real-time update broadcasting

Key dependencies:

• NetworkX - Graph data structure and algorithms
• grand-cypher - Cypher query support
• sentence-transformers - Embedding-based fuzzy matching
• FastAPI - Visualisation web server
• D3.js - Force-directed graph visualisation

Things to Know

It's transient. Graphs live in memory only. When the server stops, they're gone. This is by design - it's a working memory tool, not a database. If you need persistence, export to JSON and import later.

Fuzzy matching is on by default. Type "auth service" and it'll match "AuthService". It uses three strategies: exact match, normalised match (case/whitespace), and embedding similarity for semantic matches. Usually this is what you want.

Multiple graphs are supported. Each graph is independent. Default graph is called "default". Use the graph parameter on any tool to work with a different one.

Cypher has quirks. Use double quotes for strings (single quotes don't work). Edge type syntax [r:type] doesn't work - use WHERE r.relation = "type" instead. The server tries to auto-fix common mistakes but check the error messages if something's off.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run the server directly
python -m mcp_graph_engine.server

Contributing

Issues and PRs welcome. Keep it simple, test your changes, and don't break the existing tools.

License

MIT. See LICENSE for details.

---

Built by utilitydelta. If you find this useful, star the repo or let me know what you're using it for.