Neo4j MCP Server

This project creates a Model Context Protocol (MCP) server that connects to a Neo4j graph database, exposing database schemas, providing Cypher query tools, and including prompts for common data analysis tasks.

Features

• Neo4j Database Connection: Securely connects to your company's Neo4j database
• Schema Resources: Exposes database schema information as MCP resources
• Cypher Query Tools: Provides tools for running read-only Cypher queries
• Analysis Prompts: Includes pre-built prompts for common data analysis tasks

Installation

Prerequisites

• Python 3.8+
• Neo4j database
• uv (recommended) or pip

Setup

1. Clone this repository or create a new project:

   uv init my-neo4j-project
   cd my-neo4j-project
   

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate  # On Unix/MacOS
   # or
   .venv\Scripts\activate     # On Windows
   

3. Install dependencies:

   uv add "mcp[cli]" neo4j python-dotenv
   

4. Create a .env file with your Neo4j credentials:

   NEO4J_URI=bolt://localhost:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=your_password
   

Usage

Development Mode

Test the server using the MCP Inspector:

mcp dev neo4j_server.py

This opens an interactive interface where you can explore the server's resources, tools, and prompts.

Claude Desktop Integration

Install the server in Claude Desktop:

mcp install neo4j_server.py --name "Neo4j Explorer"

Direct Execution

Run the server directly:

python neo4j_server.py

Server Capabilities

Resources

• Complete Schema (neo4j://schema): Provides a comprehensive view of nodes, relationships, and properties
• Node Labels (neo4j://labels): Lists all node types in the database
• Relationship Types (neo4j://relationships): Lists all relationship types
• Node Properties (neo4j://nodes/{label}/properties): Shows properties for specific node types

Tools

• Execute Cypher: Runs read-only Cypher queries with security checks
• Count Nodes: Counts nodes with a specific label
• Find Relationships: Discovers relationships between node types

Prompts

• Explore Schema: General database structure exploration
• Analyze Data: In-depth analysis of specific node types
• Find Paths: Discovering connections between different node types

Security Features

• Read-only operations enforced through query validation
• Credential protection using environment variables
• Comprehensive error handling
• Protection against common security vulnerabilities

Troubleshooting

If you encounter connection issues:

1. Verify your Neo4j credentials in the .env file
2. Ensure your Neo4j database is running and accessible
3. Check the server logs for detailed error messages
4. Test connectivity using the MCP Inspector: mcp dev neo4j_server.py

Extending the Server

You can extend this server by:

1. Adding more specialized resources for specific data views
2. Creating additional analysis tools for your specific domain
3. Implementing visualization tools that return image data
4. Adding authentication for multi-user environments
5. Implementing caching for frequently accessed schema information

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Citations: [1] https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/19272244/08039fc9-fa60-4099-be05-371379047242/README-1.md [2] https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/19272244/3850f173-6e5a-4a8a-9e1e-80961fde62f9/llms-full.txt