ChatGPT Graph UI MCP

A ChatGPT-compatible MCP (Model Context Protocol) application that provides interactive Neo4j graph visualization and manipulation through natural language.

Features

Interactive Graph Visualization: Real-time rendering of Neo4j graphs with React Flow
Table View: Browse nodes and relationships in a structured table format
Natural Language Interface: Query and manipulate your graph through ChatGPT
11 Comprehensive MCP Tools:
- visualize_graph - Display the entire graph or filtered results
- query_graph - Execute custom Cypher queries
- add_node - Create new nodes with labels and properties
- add_edge - Create relationships between nodes
- add_node_and_edge - Atomic operation to create both node and relationship
- describe_schema - Get comprehensive database schema information with samples
- search_nodes - Search for nodes by property values (exact or partial matching)
- find_path - Find shortest path between two nodes
- update_node - Update properties of existing nodes
- get_neighbors - Get all connected nodes with filtering options
- batch_create_nodes - Create multiple nodes and relationships in one operation
Dual Viewing Modes: Switch between interactive graph visualization and table view
Color-coded Nodes: Different colors for Person, Company, Product, Location, Event types
Interactive Features: Click nodes to view properties, drag to rearrange, zoom and pan
ChatGPT Integration: Renders beautifully inside ChatGPT's interface

Architecture

This application combines:

ChatGPT Apps SDK - For iframe rendering and ChatGPT compatibility
MCP Server - Protocol for tool-based AI interactions
Neo4j Database - Graph database for storing and querying data
Next.js 15 - React framework with App Router and Turbopack
React Flow (@xyflow/react) - Interactive graph visualization with built-in controls
Multiple Visualization Libraries - Support for Neo4j NVL, Cytoscape, Vis-Network for experimentation

Getting Started

Prerequisites

Node.js 18+ and pnpm
Neo4j database (cloud or local instance)
ChatGPT account with developer mode/MCP support

Installation

Clone the repository:

git clone <your-repo>
cd chatgpt-graph-ui-mcp

Install dependencies:

pnpm install

Configure environment variables:

cp .env.example .env

Edit .env and add your Neo4j credentials:

NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Run the development server:

pnpm dev

Open http://localhost:3000 to see the app.

Deployment

Vercel Deployment

Push your code to GitHub
Import the project to Vercel
Add environment variables in Vercel dashboard
Deploy!

The app will automatically configure the correct base URL for production.

ChatGPT Integration

After deploying, get your MCP endpoint URL: https://your-app.vercel.app/mcp
In ChatGPT, go to Settings → Connectors
Add a new MCP server with your endpoint URL
Start chatting!

Usage Examples

Once connected to ChatGPT, try these prompts:

Schema Discovery

"Describe the database schema"
"Show me what types of nodes and relationships exist"
"What properties do Person nodes have?"

Visualization

"Show me the knowledge graph"
"Visualize all nodes and relationships"
"Display the graph with a limit of 50 nodes"
"Switch to table view to see all the data"

Querying

"Find all people who work at companies"
"Show me all nodes labeled Person"
"Query the graph for relationships of type KNOWS"

Searching

"Search for nodes with name containing 'Alice'"
"Find all Person nodes where the name property matches 'Bob'"
"Search for companies in San Francisco"

Path Finding

"Find the shortest path between node 1 and node 5"
"How is Alice connected to Acme Corp?"
"Show me the relationship path from node 10 to node 15"

Creating Nodes

"Add a Person node named Alice with age 30"
"Create a Company called Acme Corp in San Francisco"
"Add a Product node called Widget with price 99.99"

Creating Relationships

"Connect Alice to Acme Corp with a WORKS_FOR relationship"
"Create a KNOWS relationship from node 1 to node 2"
"Link Person Alice to Location San Francisco with LIVES_IN"

Updating Nodes

"Update node 5 to add a new property email: alice@example.com"
"Change the age property of node 3 to 31"
"Update Alice's properties"

Batch Operations

"Create 3 Person nodes: Alice (age 30), Bob (age 25), Carol (age 28)"
"Create a team structure with 5 people and connect them with WORKS_WITH relationships"
"Build a company org chart with departments and employees"

Exploration

"Show me all neighbors of node 10"
"What nodes are connected to Alice?"
"Get all nodes within 2 hops of node 5"

Combined Operations

"Create a Person named Bob and connect him to Alice with KNOWS"
"Add a Product called Premium Widget and link it to Acme Corp with MANUFACTURED_BY"

Project Structure

chatgpt-graph-ui-mcp/
├── app/
│   ├── mcp/route.ts              # MCP server with 11 tools + 1 resource
│   ├── graph-widget/page.tsx     # Widget page with Graph + Table views
│   ├── layout.tsx                # Root layout with SDK bootstrap
│   ├── page.tsx                  # Home page with documentation
│   └── globals.css               # Global styles
├── components/
│   ├── GraphVisualization.tsx    # Neo4j NVL visualization (legacy)
│   ├── GraphVisualization2.tsx   # Vis-Network visualization (experimental)
│   ├── GraphVisualization3.tsx   # Cytoscape visualization (experimental)
│   ├── GraphVisualization4.tsx   # React Flow visualization (ACTIVE)
│   └── TableView.tsx             # Table view for nodes and relationships
├── lib/
│   └── neo4j.ts                  # Neo4j driver singleton
├── middleware.ts                 # CORS middleware for RSC
├── baseUrl.ts                    # Base URL detection (dev/prod)
├── next.config.ts                # Next.js configuration
├── package.json                  # Dependencies
└── tsconfig.json                 # TypeScript configuration

MCP Tools Reference

1. visualize_graph

Input: query (optional Cypher), limit (optional, default 100)
Output: Graph data with nodes and relationships
Triggers: Interactive graph/table widget
Use case: Display the entire graph or filtered subsets

2. query_graph

Input: query (Cypher string), parameters (optional object)
Output: Query results as graph data
Triggers: Interactive graph/table widget
Use case: Execute custom Cypher queries for advanced filtering

3. add_node

Input: label (string), properties (object)
Output: Created node + updated graph context
Triggers: Interactive graph/table widget
Use case: Create single nodes with labels and properties

4. add_edge

Input: fromNodeId, toNodeId, relationshipType, properties (optional)
Output: Created relationship + updated graph context
Triggers: Interactive graph/table widget
Use case: Connect two existing nodes with a relationship

5. add_node_and_edge

Input: newNodeLabel, newNodeProperties, existingNodeId, relationshipType, relationshipDirection, relationshipProperties (optional)
Output: Created node + relationship + updated graph context
Triggers: Interactive graph/table widget
Use case: Atomic operation to create node and connect it in one step

6. describe_schema

Input: includeSamples (boolean, optional, default true)
Output: Comprehensive schema information with node labels, relationships, properties, patterns, and samples
Use case: Understand the database structure before querying

7. search_nodes

Input: label (optional), propertyName, searchValue, exactMatch (optional, default false), limit (optional, default 50)
Output: Matching nodes with their relationships
Triggers: Interactive graph/table widget
Use case: Find nodes by property values using exact or partial matching

8. find_path

Input: fromNodeId, toNodeId, maxDepth (optional, default 5)
Output: Shortest path between two nodes
Triggers: Interactive graph/table widget
Use case: Discover how two entities are connected

9. update_node

Input: nodeId, properties (object), replace (optional, default false)
Output: Updated node with new properties + graph context
Triggers: Interactive graph/table widget
Use case: Modify existing node properties or add new ones

10. get_neighbors

Input: nodeId, relationshipType (optional), direction (optional, default 'both'), depth (optional, default 1), limit (optional, default 100)
Output: All connected nodes within specified depth
Triggers: Interactive graph/table widget
Use case: Explore the neighborhood of a node with filtering

11. batch_create_nodes

Input: nodes (array of node specs), relationships (optional array of relationship specs)
Output: All created nodes and relationships
Triggers: Interactive graph/table widget
Use case: Efficiently create multiple nodes and relationships in one operation

Development

Running Tests

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

Tech Stack

Next.js 15.5.4 - React framework with Turbopack
React 19 - UI library
Neo4j Driver 6.0.0 - Database connectivity
React Flow (@xyflow/react 12.8.6) - Primary graph visualization library
@neo4j-nvl/react 1.0.0 - Official Neo4j visualization (experimental)
Cytoscape 3.33.1 - Alternative graph visualization (experimental)
Vis-Network 10.0.2 + Neovis.js 2.1.0 - Alternative visualization (experimental)
MCP Handler 1.0.3 - MCP protocol implementation
@modelcontextprotocol/sdk 1.20.1 - MCP SDK
Zod 3.25 - Schema validation
Tailwind CSS 4 - Styling

How It Works

ChatGPT calls MCP tool (e.g., "visualize_graph" or "describe_schema")
Tool queries Neo4j and returns graph data or schema information
Tool metadata points to graph visualization resource (for graph tools)
ChatGPT fetches the graph-widget page HTML
Widget renders in ChatGPT's iframe with two tabs: Graph and Table
SDK bootstrap patches browser APIs (fetch, history, links)
Graph data flows via window.openai.toolOutput
React Flow renders the interactive graph OR TableView displays data in tables
User interacts with nodes/relationships in ChatGPT
- Graph view: Click nodes, drag to rearrange, zoom/pan, use minimap
- Table view: Sort and browse nodes/relationships in structured format

Troubleshooting

"No graph data available"

Ensure your Neo4j database has data
Check Neo4j credentials in .env
Verify database connection

"Error querying graph"

Check Cypher query syntax
Ensure node IDs exist when creating relationships
Check Neo4j server status

Widget not rendering

Verify baseURL is correct for your environment
Check CORS middleware is enabled
Ensure MCP endpoint is accessible

Static assets 404

Ensure assetPrefix is set in next.config.ts
Rebuild the app after config changes

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT

Credits

Built with:

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.claude		.claude
app		app
components		components
lib		lib
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
baseUrl.ts		baseUrl.ts
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

jacobgoren-sb/graphsomeknowledge

Folders and files

Latest commit

History

Repository files navigation