Serena as an MCP server for Hermes: LSP-powered find-references and safe renames

Step-by-Step Breakdown

1. Install and initialise Serena.

   Install with uv (it creates its own virtual environment), then initialise it in your project. The language back end is set to LSP, the same technology behind go-to-definition in VS Code and PyCharm.

2. Register it with Hermes as an MCP server.

   Add an MCP server named serena that launches the Serena binary with start-mcp-server in ide-assistant context, scoped to your project path. Hermes connects, lists the 21 tools, and asks whether to enable them (Y). The entry is saved to the Hermes config file.

   Serena's own README documents the launch command in this general form. Check it for your version:

   serena start-mcp-server --context ide-assistant --project /path/to/your/project

3. Start Hermes and confirm the server.

   Launch Hermes normally. The startup output lists the Serena MCP connection. Use the latest Hermes. He was on a current build and saw frequent update prompts.

4. Semantic search.

   "Find all references to the grade column across this codebase." Result: references grouped by role (a column definition on line 44, a Pydantic field on line 80, a SQL join on line 123). Hermes flagged that join as broken because it compared against a column that doesn't exist. Plain grep returned 32 undifferentiated matches.

5. Safe rename.

   "Rename shipment_summary to get_tonnage_by_grade everywhere." Serena renames the symbol, not the string, so comments and similarly named variables are left alone. Hermes then verified the change.

Gotchas & Caveats

• Enabling all 21 tools adds their descriptions to every turn's context. If context is tight, enable only the ones you use.
• LSP quality depends on the language. Python and TypeScript servers are mature. Check yours before relying on renames.
• The same MCP registration pattern works for Claude Code, OpenCode and OpenClaw.