MCP server for Neo4j database integration, providing tools to connect, query, and manage Neo4j databases
neo4j-mcp has 6 tools with explicit Zod schema definitions and descriptions, but critical quality gaps prevent a higher score. All tools have basic descriptions (10 - 100 chars), but most are generic and lack actionable guidance for LLM selection. Naming is inconsistent: 'Connect' vs 'ConnectWithEnv' violates verb_noun convention ('ConnectWithEnv' is gerund-like; should be 'GetConnection' or 'connect_with_env'). Schemas use Zod which compiles to JSON Schema, but parameter descriptions are minimal (5 - 10 words on average), violating the 'every parameter needs description' rule (baseline: 94% of A+ tools have full param descriptions). No output schema documentation, the Query tool returns records but the structure is not defined. No pagination support for large result sets. No idempotency markers. Error handling returns error text but does not guide recovery (no 'retry' hints, no 'try X instead' suggestions). Security: credentials accepted as parameters in 'Connect' tool (uri, username, password), violating secret-injection pattern (source: pattern:secret-injection). No permission checks or audit trail. ConnectWithEnv relies on env vars but no validation that they are set.
Connect to a Neo4j database with explicit credentials
Connect to Neo4j using environment variables
Disconnect from the Neo4j database
Get the current Neo4j connection status
Retrieve information about the connected Neo4j database
Execute a Cypher query against the Neo4j database
Credentials exposed as tool parameters (Connect tool accepts uri, username, password as parameters). Violates secret-injection pattern, credentials will appear in agent logs, traces, and prompt history.
No output schema documentation for Query and GetDatabaseInfo tools. LLMs cannot predict response structure, field names, or types. Must infer from response text alone, increasing hallucination risk.
Inconsistent naming: 'ConnectWithEnv' violates verb_noun convention. Should be 'connect_via_environment' or 'open_env_connection'. LLMs may struggle to infer intent from gerund+preposition pattern.
Parameter descriptions are minimal (5 - 10 words). 'Neo4j database username', 'Query parameters (optional)' do not explain constraints, format, or dependencies. Baseline: 94% of A+ tools have 50+ char param descriptions.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 49 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 39 | - | v1 |
No pagination support. Query tool can return thousands of records but accepts no limit/page parameters and does not document result cap. Risks context window exhaustion.
Error handling returns error text but does not guide recovery. 'Error connecting to Neo4j: <error>' gives LLM no hints (retry? check credentials? call Connect first?). Baseline: A+ tools include 'Try X next' guidance.
No permission checks or audit trail. Tools like Query and Disconnect execute without validating caller authority or logging who/what/when. Missing scope declarations (e.g. 'read:cypher', 'write:cypher').
No idempotency markers or confirmation for destructive operations. Disconnect removes the active session without confirmation, and calling Query twice with identical input may have different side effects if database state changed.
ConnectWithEnv does not document which environment variables are expected (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE?). No validation that vars are set or usable error message if missing.