Hermes is a specialized MCP server for Neo4j Cypher quality engineering — review, optimization, explanation, generation, data modeling health, and Graph Data Science advisory. It integrates with LLM-powered IDEs to provide expert-level Cypher assistance through conversational interaction.
It runs as an MCP server inside VS Code, meaning all interaction happens conversationally through Copilot Chat. The AI handles query analysis, optimization debates, schema validation, and GDS recommendations while you stay in control of every decision.
Want to try it out? Follow the Trial Guide — a hands-on walkthrough with real Cypher queries, ready to run in ~10 minutes.
INPUT PROCESSING OUTPUT
───── ────────── ──────
Cypher queries ──► Linter (19 deterministic Review reports with
Neo4j database(s) │ rules, CY001-CY027) severity, fixes, scores
│ + 23 KB rules
▼
Schema (optional: ──► Effort (simple/medium/ Optimized queries with
arrows.app JSON import) Router complex routing) consensus scoring
│
Natural language ──► Workers (Cypher, Modeling, Explanations, generated
descriptions │ GDS, Metrics) queries, GDS recipes
▼
Multi-Agent (Performance vs Modeling health reports,
Debate Readability agents) index recommendations
10 MCP Tools · 6 Resources · 4 Prompts
155+ Knowledge Base files
Multi-database support
Configure LLM models, cost thresholds, and more in config.yaml. See Configuration Guide for all required environment variables including LLM provider credentials (ANTHROPIC_API_KEY for direct API, GCP_PROJECT_ID + ADC for Vertex AI, or GOOGLE_API_KEY for Google Gemini) and NEO4J_URI, NEO4J_PASSWORD.
| Capability | Input | Output |
|---|---|---|
| Cypher Review | Cypher query | Lint findings (19 linter rules + 23 KB rules), severity scores, fix suggestions, schema health check (constraints/indexes) |
| Cypher Optimize | Cypher query | Optimized query with performance/readability trade-off analysis |
| Cypher Explain | Cypher query | Clause-by-clause breakdown, operator descriptions, execution plan |
| Cypher Generate | Natural language description | Validated Cypher query with confidence scoring |
| Modeling Health | Neo4j database connection | Anti-pattern detection, index/constraint recommendations, health score |
| GDS Recommend | Use case or graph question | Algorithm recommendation from 39+ GDS algorithms with code examples |
| Multi-Database | Multiple Neo4j connections | Cross-database query comparison, plan diffs, metrics |
| Sessions | Arrows.app JSON (optional) | Persistent context with schema-aware validation |
Hermes is multilingual by default — it automatically detects the language of each message and responds in the same language. Primary languages: Português (pt-br), English (en), Español (es).
| Document | Description |
|---|---|
| Use Cases | What you can do with Hermes — scenario by scenario |
| Setup Guide | VS Code, Copilot, and MCP server setup |
| Installation | Installing, upgrading, and activating Hermes |
| Configuration | Environment variables, API keys, Neo4j setup, config.yaml |
| Data Privacy & Security | What data goes where — LLM, Neo4j, local |
| Architecture | Deep dive into how the system works internally |
| Trial Guide | Hands-on walkthrough with real queries (~10 min) |
| Troubleshooting | Known issues, common errors, and how to fix them |
| Reporting Issues | How to report bugs and what to include |
Requires Python 3.13. See Installation Guide for details.
Install from the .whl file you received:
pip install hermes-<VERSION>-py3-none-any.whlTo upgrade an existing installation:
pip install --force-reinstall hermes-<VERSION>-py3-none-any.whlReplace
<VERSION>with the actual version (e.g.,2026.5.1.1). Using a virtual environment? Activate it first (source hermes_env/bin/activateon Mac/Linux orhermes_env\Scripts\Activate.ps1on Windows). See the Installation Guide for detailed setup with virtual environments, MCP configuration, and VS Code integration.
All interaction happens through Copilot Chat in VS Code. Every message must start with Hermes,.
Hermes, review this query: MATCH (n) RETURN n
Hermes, optimize MATCH (u:User)-[:BOUGHT]->(p:Product) RETURN u, collect(p)
Hermes, explain MATCH (a)-[:KNOWS*1..5]->(b) WHERE a.name = 'Alice' RETURN b
Hermes, generate a query to find users who bought the same products
Hermes, start session e-commerce
Hermes, check model health
Hermes, recommend GDS algorithm for community detection
| Command | What it does |
|---|---|
Hermes, review <query> |
Analyze a Cypher query for quality issues (19 linter rules + 23 KB rules, schema validation, execution plan analysis, schema health check) |
Hermes, optimize <query> |
Optimize a query with effort-based routing (simple: fast path, complex: multi-agent debate) |
Hermes, explain <query> |
Get a clause-by-clause breakdown with operator descriptions and execution plan |
Hermes, generate <description> |
Generate a Cypher query from natural language with auto-validation loop |
Hermes, check model health |
Analyze the connected Neo4j database for anti-patterns and recommend improvements |
Hermes, recommend GDS <use case> |
Get algorithm recommendations from 39+ GDS algorithms with code examples |
Hermes, start session <name> |
Start a persistent session for multi-turn analysis with context |
Hermes, import model |
Import an arrows.app JSON schema for schema-aware validation |
Hermes, compare schema |
Compare imported model vs live database schema (drift detection) |
Hermes, list databases |
Show all configured Neo4j databases and their status |
Hermes, compare databases |
Compare query execution across multiple databases |
Tip: You can speak in any language — Hermes detects and responds in the same language automatically.
For multi-turn analysis with persistent context:
Hermes, start session e-commerce # Create session, bind to database
Hermes, import model # Import arrows.app JSON schema
Hermes, compare schema # Check model vs database drift
Hermes, review MATCH (n:Product) RETURN n # Schema-aware review
Hermes, close session # End session
- Determinism first — Linting is 100% rule-based (no LLM, 19 linter rules + 23 KB rules). LLM is used only for optimization and generation
- Scaling by effort — Simple queries get fast deterministic analysis; complex queries trigger multi-agent debate
- Multi-perspective — Optimization uses opposing agents (Performance vs Readability) with consensus scoring
- Safety by default — Destructive operations require explicit confirmation; write queries blocked by default in PROFILE
| Type | Count | Examples |
|---|---|---|
| Tools | 10 | cypher_review, cypher_optimize, cypher_explain, cypher_generate, modeling_health, gds_recommend, databases, compare_databases, session, onboarding |
| Resources | 6 | hermes://config, hermes://sessions, hermes://session/{id}, hermes://status, hermes://rules, hermes://kb/playbooks |
| Prompts | 4 | analyze_data, debug_pipeline, cypher_best_practices, troubleshoot_performance |
┌─────────────────────────────────────────────────────────────────┐
│ VS Code / Cursor / LLM Client │
└───────────────────────────┬─────────────────────────────────────┘
│ MCP Protocol (stdio)
▼
┌─────────────────────────────────────────────────────────────────┐
│ hermes/server.py (FastMCP Gateway) │
│ │
│ Tools ─── cypher_review | cypher_optimize | cypher_explain │
│ cypher_generate | modeling_health | gds_recommend │
│ databases | compare_databases | session | onboarding │
│ │
│ Resources ─── config | sessions | status | rules | playbooks │
│ Prompts ──── analyze_data | debug_pipeline | best_practices │
└───────────────────────────┬─────────────────────────────────────┘
│
┌─────────────────┼─────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────────┐ ┌──────────────┐
│ Linter │ │ Effort Router │ │ Workers │
│ (19 rules │ │ simple/med/comp │ │ Cypher/GDS/ │
│ + 23 KB) │ │ │ │ Modeling/ │
└─────────────┘ └────────┬────────┘ │ Metrics │
│ └──────────────┘
┌─────────┼─────────┐
▼ ▼
┌──────────────┐ ┌───────────────────┐
│ Fast Path │ │ Multi-Agent Debate │
│(deterministic)│ │ Perf vs Readability│
└──────────────┘ │ + Consensus Score │
└───────────────────┘
See docs/ARCHITECTURE.md for full details.
Hermes is proprietary software — it is not open source. It is provided at no cost for evaluation and personal use only. All rights are reserved by the author. See the full LICENSE file for details.
Key points:
- Free to evaluate — install and use for testing, learning, or personal projects
- No redistribution — do not share, resell, or repackage the software
- No modification — do not create derivative works or reverse engineer
- No commercial use without prior written consent from the author
- License key required — the software will not operate without a valid key
For commercial licensing or questions, contact the author via GitHub.
Hermes requires a valid license key to operate.
To activate, add to your .env file:
HERMES_LICENSE=HERMES-LIC-<your-license-key>Alternatively, save the license string to ~/.hermes-license (one line, no quotes).
Trial license (expires 2026-05-31):
HERMES-LIC-eyJjdXN0b21lciI6Ikhlcm1lcyBUcmlhbCIsImV4cGlyZXMiOiIyMDI2LTA1LTMxVDIzOjU5OjU5KzAwOjAwIiwiZmVhdHVyZXMiOlsiaGVybWVzLW1jcCJdLCJpc3N1ZWQiOiIyMDI2LTA1LTExVDAxOjUyOjUxLjkyMzkzNiswMDowMCIsImxpY2Vuc2VfaWQiOiIxNjU2OTAyMy0yYjUyLTQyMjUtYTc4Yy01OTEyZDg4NmMzZmYiLCJ0eXBlIjoidGltZWQiLCJ2IjoxfQ.gEWNXU6t9c3VPk1zBo7Q8ooJpQ9vmhOFeG61EBWFRWLY1RG4Uu6hPXGwHjCcSk6TZ-m67qKsdq3i957as4vaBg
See the full LICENSE file for complete legal terms.
This software is proprietary and is not open source. It is provided at no cost for evaluation and personal use, but all rights are reserved by the author. Redistribution, modification, reverse engineering, or commercial use without prior written consent is strictly prohibited.
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY — WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE — ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
By downloading, installing, or using this software, you acknowledge and agree that:
- The author assumes no responsibility for any damage, data loss, system instability, or any other adverse effects resulting from the use of this software.
- The author assumes no responsibility for the accuracy, completeness, or reliability of any output generated by this software — including but not limited to Cypher query suggestions, optimization recommendations, data modeling advice, and any other analysis results.
- You use this software entirely at your own risk.
- This software sends data to external LLM APIs (Claude via Anthropic API or Google Vertex AI, or Google Gemini via Generative Language API) as part of query analysis — including Cypher queries, schema metadata, and execution plans. Full database contents are not sent to the LLM. See Data Privacy & Security for a detailed breakdown of what data goes where.
- This software interacts with third-party services (Anthropic API, Google Vertex AI, Google Gemini, Neo4j). The author is not responsible for costs, data handling, or any issues arising from those services. You are solely responsible for managing your own API keys, credentials, and associated costs.