Add Custom Tools to Hermes Agent
Extend Hermes Agent with custom tools — shell scripts, APIs, MCP servers, and external integrations.
Hermes ships with 40+ built-in tools, but its real power comes from extensibility — you can add shell scripts, HTTP API integrations, MCP servers, and custom plugins to make Hermes do almost anything.
Before you start:
- ☑Hermes Agent installed
- ☑Basic shell scripting knowledge for custom tools
- ☑Optional: an MCP server or external API you want to connect
Steps
- 1
Understand tool types
Hermes supports shell tools, HTTP API tools, MCP servers, and built-in plugins
- 2
Create a shell tool
Write a bash script in ~/.hermes/tools/ and describe it in a tool.yaml manifest
- 3
Add an MCP server
Configure MCP servers in config.yaml under mcp: servers: with the server command and args
- 4
Add an API tool
Define HTTP endpoints in tool.yaml with URL, method, headers, and parameter mapping
- 5
Test the tool
Ask Hermes to use your new tool and verify it executes correctly
- 6
Publish as a skill
Wrap your tool in a skill folder with SKILL.md for others to reuse
Pro Tips
- 💡MCP (Model Context Protocol) is the fastest way to add third-party integrations — configure existing MCP servers in config.yaml under 'mcp: servers:'
- 💡Wrap custom tools in a skill folder (SKILL.md + scripts/) so the tool comes with instructions on when and how to use it
- 💡Test new tools in 'hermes chat' before deploying to production — ask Hermes to use the tool explicitly and check the output
Troubleshooting
❌ Shell tool runs but Hermes can't find the executable
✅ Specify the full path to the executable in your tool.yaml manifest. Hermes runs tools with a minimal PATH — don't rely on user-level shell aliases.
❌ MCP server fails to connect
✅ Check that the MCP server process starts correctly on its own before adding it to Hermes. Run the server command manually and verify it outputs valid JSON-RPC responses.
❌ API tool returns correct data but Hermes doesn't use it
✅ The tool's response format may not match what Hermes expects. Check that your tool.yaml defines the output schema clearly so Hermes can parse and reason about the response.