mcp-neo4j

Executes Cypher queries against Neo4j databases and provides Text2Cypher workflow capabilities that translate natural language prompts into executable Cypher queries using LLM reasoning. The mcp-neo4j-cypher server uses fastMCP v2.x with @mcp.tool decorators to expose query execution as MCP tools, integrating Neo4j AsyncDriver (>=5.26.0) for asynchronous database connectivity and Pydantic models for structured input validation and response formatting.

Provides a Neo4j-backed memory system for AI agents that stores facts, relationships, and context as a persistent knowledge graph, enabling semantic search and retrieval across agent sessions. The mcp-neo4j-memory server implements a data model architecture that maps agent interactions into graph nodes and relationships, with search and retrieval tools that query the knowledge graph using vector embeddings or Cypher-based pattern matching to surface relevant context for LLM reasoning.

Provides Claude Desktop integration through manifest.json configuration files that declare MCP server availability, transport mode, and connection parameters. Each server includes a manifest.json that specifies the server name, description, command to launch (stdio), and optional HTTP endpoint configuration. Claude Desktop reads these manifests to discover and connect to MCP servers, enabling seamless integration without manual configuration. The manifest pattern allows users to enable/disable servers and switch between local and remote deployments by editing configuration.

Enables AI agents and developers to design, validate, and visualize Neo4j graph data models through MCP tools that generate model definitions, validate schema constraints, and produce visual representations. The mcp-neo4j-data-modeling server integrates with Arrows (Neo4j's diagram tool) to export models as visualizations, uses Pydantic models for schema validation, and provides tools for Cypher generation from model definitions, allowing agents to reason about data structure and generate schema-aware queries.

Manages Neo4j Aura cloud database instances through MCP tools that authenticate with Aura API credentials and expose instance lifecycle operations (create, delete, pause, resume, update). The mcp-neo4j-cloud-aura-api server implements authentication patterns for Aura API, uses Pydantic models for request/response validation, and provides tools for querying instance status, managing backups, and configuring instance parameters without direct database access.

Provides flexible transport layer abstraction for all four MCP servers, supporting stdio (for direct process communication), HTTP with Server-Sent Events (for network access), and containerized Docker deployment. Built on Starlette middleware for HTTP transport, with CORS and TrustedHost security middleware, allowing a single MCP server implementation to be deployed across multiple transport modes without code changes. Configuration is managed through environment variables and config files, with Docker Compose templates provided for multi-server deployments.

Implements type-safe MCP tool definitions using Pydantic models for input validation and structured response formatting across all four servers. Each MCP tool is decorated with @mcp.tool and uses Pydantic models to define required/optional parameters, validate types, and provide schema documentation. Responses are formatted as structured JSON objects matching Pydantic output models, ensuring LLM clients receive well-typed, validated data that can be reliably parsed and acted upon.

Integrates Neo4j's asynchronous driver (>=5.26.0) into MCP servers to enable non-blocking database operations that don't stall the MCP event loop. The Cypher and Memory servers use AsyncDriver with async/await patterns to execute queries concurrently, allowing multiple MCP tool invocations to query the database in parallel without blocking. Connection pooling and session management are handled by the driver, with configurable connection parameters (URI, auth, encryption) passed via environment variables.

Provides centralized configuration management for all MCP servers through environment variables and optional config files, enabling flexible deployment across local, cloud, and containerized environments. Configuration covers database connection parameters (Neo4j URI, auth), transport settings (stdio, HTTP host/port), security options (CORS origins, TrustedHost), and server-specific settings (LLM API keys, Aura credentials). Configuration is loaded at server startup and validated using Pydantic models, with sensible defaults for development and strict requirements for production.

Organizes four independent MCP server implementations (mcp-neo4j-cypher, mcp-neo4j-data-modeling, mcp-neo4j-memory, mcp-neo4j-aura-manager) as separate packages within a monorepo, each with independent versioning, PyPI publication, and deployment lifecycle. Each server has its own pyproject.toml, uv.lock, and CHANGELOG, enabling teams to release and deploy servers independently without coordinating versions. Shared dependencies (fastMCP, Pydantic, Neo4j driver) are managed at the monorepo level with version constraints in each server's pyproject.toml.

Implements Starlette-based security middleware for HTTP/SSE transport modes, providing Cross-Origin Resource Sharing (CORS) validation and TrustedHost enforcement to prevent unauthorized access. CORS configuration allows specifying allowed origins, methods, and headers, while TrustedHost middleware validates the Host header against a whitelist of allowed domains. Configuration is managed via environment variables, with sensible defaults for development (permissive) and strict requirements for production (explicit origin/host whitelists).