MCP Neo4j Cypher Server

MCP Neo4j Cypher Server for Cloudflare Workers

A Model Context Protocol (MCP) server that enables Claude to query Neo4j databases using natural language. Runs on Cloudflare Workers for serverless, multi-tenant deployment.

Features

• 3 MCP Tools: get_neo4j_schema, read_neo4j_cypher, write_neo4j_cypher
• Multi-tenant: Each user connects their own Neo4j database
• Serverless: Runs on Cloudflare Workers (no servers to manage)
• Permanent Tokens: Configure once, no need to renew tokens every 24 hours
• Token Management: List and revoke tokens via API for security control
• Secure: AES-256-GCM encryption, rate limiting, query validation, audit logging
• Compatible: Works with Neo4j Aura, self-hosted Neo4j 4.x/5.x

Quick Start

1. Deploy to Cloudflare

# Clone the repository
git clone https://github.com/edomioter/mcp-neo4j-cypher-ts.git
cd mcp-neo4j-cypher-ts

# Install dependencies
npm install

# Create Cloudflare resources
npx wrangler d1 create mcp-neo4j-users
npx wrangler kv namespace create SESSIONS

# Update wrangler.toml with the IDs from above

# Set encryption key
npx wrangler secret put ENCRYPTION_KEY
# Enter a 32+ character random string

# Initialize database
npx wrangler d1 execute mcp-neo4j-users --file=schema.sql

# Deploy
npx wrangler deploy

2. Configure Your Neo4j Connection

1. Visit https://your-worker.workers.dev/setup
2. Enter your Neo4j credentials:

• URI: neo4j+s://xxxxx.databases.neo4j.io (Aura) or your server
• Username: Usually neo4j
• Password: Your database password
• Database: Usually neo4j

1. Click "Test & Save Connection"
2. Copy the permanent access token (valid indefinitely, no expiration)

3. Use with Claude

For Claude.ai: Add the server URL with your token as a parameter: `` https://your-worker.workers.dev/mcp?token=YOUR_PERMANENT_TOKEN ``

For Claude Desktop: Add to your claude_desktop_config.json: ``json { "mcpServers": { "neo4j": { "url": "https://your-worker.workers.dev/mcp", "headers": { "Authorization": "Bearer YOUR_PERMANENT_TOKEN" } } } } ``

💡 Note: Tokens are permanent and don't expire. You only need to configure this once!

Now you can ask Claude things like:

• "What's the schema of my Neo4j database?"
• "Find all Person nodes and their relationships"
• "Create a new Movie node with title 'Inception'"

Available Tools

| Tool | Description | |------|-------------| | get_neo4j_schema | Retrieves database schema (labels, properties, relationships) | | read_neo4j_cypher | Executes read-only Cypher queries (MATCH, RETURN) | | write_neo4j_cypher | Executes write queries (CREATE, MERGE, DELETE) |

Token Management

Your access tokens are permanent and don't expire. However, you can manage them for security:

List Active Tokens

curl -X GET https://your-worker.workers.dev/api/tokens \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoke a Token

curl -X POST https://your-worker.workers.dev/api/tokens/revoke \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "TOKEN_TO_REVOKE"}'

⚠️ Security: Keep your tokens secure. If compromised, revoke them immediately and create a new one.

Documentation

• User Guide - Complete guide for integrating with Claude.ai
• Deployment Guide - Detailed setup and configuration
• Security - Rate limiting, blocked queries, encryption
• API Reference - HTTP endpoints and MCP tools

Development

# Install dependencies
npm install

# Run locally
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Claude    │────▶│ Cloudflare Worker│────▶│  Neo4j Aura │
│  (claude.ai)│◀────│   (MCP Server)   │◀────│  (Database) │
└─────────────┘     └──────────────────┘     └─────────────┘
                            │
                    ┌───────┴───────┐
                    │               │
                ┌───▼───┐     ┌─────▼─────┐
                │  D1   │     │    KV     │
                │(Users)│     │(Sessions) │
                └───────┘     └───────────┘

Requirements

• Node.js 18+
• Cloudflare account (free tier works)
• Neo4j database (Aura free tier or self-hosted)

Configuration

| Environment Variable | Description | Default | |---------------------|-------------|---------| | ENCRYPTION_KEY | Secret key for encrypting credentials | Required | | DEFAULT_READ_TIMEOUT | Query timeout in seconds | 30 | | DEFAULT_TOKEN_LIMIT | Max tokens in responses | 10000 | | DEFAULT_SCHEMA_SAMPLE | Nodes to sample for schema | 1000 | | ALLOWED_ORIGINS | CORS allowed origins | https://claude.ai |

License

MIT

Credits

Based on mcp-neo4j-cypher by Neo4j Contributors.