mcorpening85/neo4j-mcp-server

Neo4j MCP Server

A Model Context Protocol (MCP) server for Neo4j database integration with Claude AI, optimized for Render deployment.

🚀 Quick Deploy to Render

Overview

This MCP server enables Claude to interact with Neo4j graph databases using natural language. It provides:

• Schema exploration - Understand your graph structure
• Cypher query execution - Run read and write queries
• Natural language interface - Ask questions about your data
• HTTP transport - Remote access via Render deployment
• Built-in health checks - Render-compatible health endpoint

Deployment Instructions

1. Deploy on Render

1. Go to Render Dashboard
2. Click New + → Web Service
3. Connect this GitHub repository
4. Render will auto-detect the render.yaml configuration
5. Add these required environment variables in Render dashboard:

   NEO4J_URI=bolt://your-neo4j-host:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your-secure-password
   

6. Click Create Web Service
7. Wait for deployment (first deploy may take 2-3 minutes)

Important: The three required environment variables (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD) must be added in your Render dashboard under the "Environment" tab. The service will not start without them.

2. Verify Deployment

Check that your service is running:

# Health check endpoint
curl https://YOUR-APP-NAME.onrender.com/health
# Should return: OK

# Root endpoint (also returns health status)
curl https://YOUR-APP-NAME.onrender.com/
# Should return: OK

3. Connect to Claude Desktop

After deployment, you'll get a URL like: https://neo4j-mcp-server.onrender.com

Add this to your Claude Desktop config:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j-render": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-APP-NAME.onrender.com/api/mcp/"
      ]
    }
  }
}

⚠️ CRITICAL: The URL MUST end with /api/mcp/ - don't forget the trailing slash!

✅ Correct: https://YOUR-APP-NAME.onrender.com/api/mcp/
❌ Wrong: https://YOUR-APP-NAME.onrender.com

Restart Claude Desktop (Cmd/Ctrl + R).

Configuration

Required Environment Variables

Optional Environment Variables

How It Works

This deployment uses a Python reverse proxy wrapper (start.py) that:

1. Runs on port 8080 (external, facing Render)
2. Handles health checks at /health and / endpoints for Render
3. Forwards all MCP requests to the internal MCP server (port 8081)
4. Provides detailed logging for troubleshooting

This architecture ensures:

• ✅ Render's health checks succeed (no "501 Unsupported method" errors)
• ✅ MCP server operates normally on internal port
• ✅ All POST/GET requests properly forwarded
• ✅ Service stays healthy and running

Local Development

Using Docker

# Build the image
docker build -t neo4j-mcp-server .

# Run with your Neo4j credentials
docker run -p 8080:8080 \
  -e NEO4J_URI=bolt://your-neo4j:7687 \
  -e NEO4J_USERNAME=neo4j \
  -e NEO4J_PASSWORD=password \
  neo4j-mcp-server

Test locally:

# Health check
curl http://localhost:8080/health

# Test MCP endpoint
curl -X POST http://localhost:8080/api/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# View logs
docker logs <container-id>

Direct Installation

# Install the package
pip install mcp-neo4j-cypher requests

# Run the wrapper script
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password

python3 start.py

Testing

Health Check

# Simple health check
curl https://YOUR-APP-NAME.onrender.com/health

# Or check the root endpoint
curl https://YOUR-APP-NAME.onrender.com/

Both should return a 200 OK status.

Test with Claude

Once connected, try these prompts in Claude:

• "What tools are available from my Neo4j MCP server?"
• "Show me the schema of my Neo4j database"
• "Find all Person nodes in the database"
• "How many nodes are in the database?"

Render Free Tier Notes

⚠️ Important: Render's free tier spins down after 15 minutes of inactivity.

• First request after sleep: ~30-60 seconds
• Subsequent requests: Fast
• Health checks keep the service alive during active use

Solutions:

• Upgrade to Starter plan ($7/month) for always-on
• Use a keep-alive service like Uptime Robot
• Accept the cold start delay (only affects first request)

Troubleshooting

"Error 501: Unsupported method ('POST')"

Cause: Your Claude Desktop config is missing /api/mcp/ at the end of the URL.

Solution: Update your claude_desktop_config.json:

{
  "mcpServers": {
    "neo4j-render": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-APP-NAME.onrender.com/api/mcp/"
      ]
    }
  }
}

Key points:

• ✅ URL must end with /api/mcp/
• ✅ Don't forget the trailing slash
• ⚠️ Replace YOUR-APP-NAME with your actual Render app name

"No open ports detected" Error

Fixed! This repository now includes a reverse proxy wrapper that properly handles Render's health checks. If you still see this error:

1. Ensure you've pulled the latest code with updated start.py and Dockerfile
2. Check that the container is building successfully in Render logs
3. Verify the healthCheckPath: /health is in your render.yaml
4. Make sure requests library is installed (should be in Dockerfile)

Service won't start

Check Render logs:

1. Go to Render Dashboard → Your Service → Logs
2. Look for error messages

Common issues:

• ❌ Missing environment variables (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD)
• ❌ Neo4j URI not accessible from Render
• ❌ Incorrect Neo4j credentials
• ❌ Neo4j firewall blocking Render's IP addresses

Solutions:

# Verify your Neo4j connection locally first
python3 -c "
from neo4j import GraphDatabase
driver = GraphDatabase.driver('YOUR_URI', auth=('USERNAME', 'PASSWORD'))
driver.verify_connectivity()
print('✓ Connection successful')
"

Claude can't connect

# Test the MCP endpoint (should get a response, even if error)
curl -X POST https://YOUR-APP-NAME.onrender.com/api/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# Check service status
curl https://YOUR-APP-NAME.onrender.com/health

Slow first request

This is normal on Render's free tier after 15 minutes of inactivity. The service spins down to save resources and needs 30-60 seconds to restart.

Neo4j Connection Issues

If logs show "Failed to establish connection":

1. Check Neo4j is running and accessible
2. Verify URI format:
   • Local: bolt://localhost:7687
   • Neo4j Aura: neo4j+s://xxxxx.databases.neo4j.io
   • Cloud instance: bolt://your-host:7687
3. Whitelist Render IPs in Neo4j firewall (for Neo4j Aura/Cloud)
4. Test connection from command line first

Documentation

• Neo4j MCP Documentation
• Model Context Protocol
• Render Documentation
• Claude Desktop MCP Setup

Architecture

┌──────────────────────────────────────────┐
│   Render (Docker Container)              │
│  ┌────────────────────────────────────┐  │
│  │  start.py (Reverse Proxy)          │  │
│  │  Port 8080 (External)              │  │
│  │  ├─ /health → 200 OK               │  │
│  │  ├─ / → 200 OK                     │  │
│  │  └─ /api/mcp/* → Forward to 8081  │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │  mcp-neo4j-cypher                  │  │
│  │  Port 8081 (Internal)              │  │
│  │  └─ /api/mcp/ → MCP Protocol      │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
           │
           ↓
    ┌──────────────┐
    │   Neo4j DB   │
    └──────────────┘

License

MIT

Credits

Built with:

• mcp-neo4j-cypher by Neo4j
• Model Context Protocol by Anthropic

Contributing

Issues and pull requests are welcome! Please ensure:

• Health checks remain functional
• Environment variables are documented
• Render compatibility is maintained