Neo4j MCP Workshop
MCP server: Neo4j MCP Workshop
Installation
npx neo4j-mcp-workshopAsk AI about Neo4j MCP Workshop
Powered by Claude Β· Grounded in docs
I know everything about Neo4j MCP Workshop. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Neo4j MCP Workshop
This repository demonstrates Model Context Protocol (MCP) server development with Neo4j graph databases. It includes both the official Neo4j MCP server for general-purpose Cypher querying and custom implementations for ecommerce applications.
Outline
- Module 1: Using the
mcp-neo4j-cypherMCP server with Claude Desktop for exploratory data analysis - Module 2: Building your own MCP server and
Module 1: Using the mcp-neo4j-cypher MCP server with Claude Desktop for exploratory data analysis
The mcp-neo4j-cypher server is a Neo4j MCP implementation that provides comprehensive Cypher query capabilities for any Neo4j database.
Features
execute_cypher- Execute arbitrary Cypher queries against your Neo4j databaseexplore_schema- Explore database schema (node labels, relationship types, property keys)get_database_info- Get information about your Neo4j database- Schema-agnostic - Works with any Neo4j database structure
- APOC Integration - Leverages Neo4j APOC plugin for enhanced functionality
Setup with Neo4j Aura and Claude Desktop
-
Create Neo4j Aura Database:
- Sign up at Neo4j Aura
- Create a new database instance
- Note your connection URI, username, and password
-
Configure Claude Desktop: Add the following to your
claude_desktop_config.json:
{
"mcpServers": {
"neo4j-database": {
"command": "uvx",
"args": [ "mcp-neo4j-cypher@0.4.1", "--transport", "stdio" ],
"env": {
"NEO4J_URI": "<YOUR_NEO4J_AURA_URI_HERE>",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<YOUR_NEO4J_PASSWORD_HERE>",
"NEO4J_DATABASE": "neo4j"
}
}
}
}
- Test the Integration:
- Restart Claude Desktop
- Ask Claude to explore your Neo4j database: "What does my Neo4j database contain?"
- Try queries like: "Find all nodes in my database" or "Show me the schema of my Neo4j database"
Module 2: Building Your Own MCP Server
Creating Custom MCP Servers
This section covers how to build your own MCP servers using different SDKs and frameworks. The examples demonstrate domain-specific implementations for ecommerce applications.
MCP Server Development SDKs
Python SDKs
FastMCP (Used in this project)
- Package:
fastmcp - Features: High-level Python framework for MCP server development
- Best for: Rapid prototyping and Python developers
- Installation:
pip install fastmcp
Official Python MCP SDK
- Package:
mcp - Features: Official Python implementation of MCP protocol
- Best for: Full control over MCP protocol implementation
- Installation:
pip install mcp
TypeScript SDKs
Official TypeScript MCP SDK (Used in this project)
- Package:
@modelcontextprotocol/sdk - Features: Official TypeScript implementation with full type safety
- Best for: TypeScript/JavaScript developers and production applications
- Installation:
npm install @modelcontextprotocol/sdk
Development Workflow
- Choose Your SDK: Select based on your language preference and requirements
- Define Tools: Design MCP tools that expose your application's functionality
- Implement Handlers: Write tool handlers that perform the actual work
- Test with MCP Inspector: Use
npx @modelcontextprotocol/inspectorfor development - Integrate with AI Clients: Connect to Claude Desktop or other MCP clients
Ecommerce MCP Server Implementation
This project includes a custom MCP server implementation designed specifically for ecommerce applications. It demonstrates how to build domain-specific MCP servers with targeted tools for business use cases.
Features
The ecommerce MCP server provides two specialized tools:
search_customer- Search for customers by name or email (case-insensitive)recommend_product- Recommend products for a customer based on co-purchase behavior
Available Implementations
Python Implementation (python/)
- Framework: FastMCP
- Package Manager: uv
- Setup:
cd python uv sync cp env.example .env # Edit .env with your Neo4j credentials uv run neo4j-mcp-ecommerce
TypeScript Implementation (ts/)
- Framework: Official TypeScript MCP SDK
- Package Manager: npm/yarn
- Setup:
cd ts npm install cp env.example .env # Edit .env with your Neo4j credentials npm run dev
Database Schema
The ecommerce servers assume a Neo4j schema with the following structure:
(:Customer {id, name, email})
(:Product {id, title})
(:Order)
(:LineItem)
(:Customer)-[:PURCHASED]->(:Order)
(:Order)-[:CONTAINS]->(:LineItem)
(:LineItem)-[:PRODUCT]->(:Product)
Environment Configuration
Both implementations require the same environment variables:
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j # optional
Testing with MCP Inspector
Test either implementation using the MCP Inspector:
npx @modelcontextprotocol/inspector
Prerequisites
- Neo4j Database: A running Neo4j instance (local, cloud, or Neo4j Aura)
- APOC Plugin: Required for mcp-neo4j-cypher (included in Neo4j Aura)
- Python: 3.10+ (for Python implementations)
- Node.js: 18.0+ (for TypeScript implementation)
- Package Manager: uv (Python) or npm/yarn (TypeScript)
Project Structure
neo4j-mcp-workshop/
βββ python/ # Python ecommerce implementation
β βββ src/neo4j_mcp/
β β βββ main.py # MCP server implementation
β βββ pyproject.toml # uv project configuration
β βββ env.example # Environment variables template
β βββ README.md # Python-specific documentation
βββ ts/ # TypeScript ecommerce implementation
β βββ src/
β β βββ index.ts # MCP server implementation
β βββ package.json # npm project configuration
β βββ tsconfig.json # TypeScript configuration
β βββ env.example # Environment variables template
β βββ README.md # TypeScript-specific documentation
βββ README.md # This file
Learning Objectives
This workshop demonstrates:
- Using Neo4j MCP Servers: Using existing Neo4j MCP servers
- Custom MCP Development: Building domain-specific MCP servers
- SDK Comparison: Working with different MCP development frameworks
- Graph Database Integration: Connecting MCP servers to Neo4j
- AI Integration: Connecting MCP servers to Claude Desktop
- Testing and Debugging: Using MCP Inspector for development
Additional Resources
- mcp-neo4j-cypher Repository - Neo4j MCP server documentation
- Model Context Protocol - MCP specification and documentation
- Neo4j Documentation - Neo4j database documentation
- Neo4j Aura - Cloud-hosted Neo4j database service
- APOC Plugin - Neo4j APOC plugin for additional procedures
- FastMCP Documentation - FastMCP Python framework
- TypeScript MCP SDK - Official TypeScript MCP SDK
