How-To Guide
Add Custom Tools to Hermes Agent
Extend Hermes Agent with custom tools — shell scripts, APIs, MCP servers, and external integrations.
Quick answer
Extend Hermes beyond its 40+ built-in tools by adding shell scripts, HTTP/API integrations, MCP servers, and custom Python plugins. Tools and skills live under ~/.hermes; MCP servers connect external capabilities. Add tools deliberately and review their access — each one widens what the agent can do, and what it can break.
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.
Managed cloud · API costs included · Skill library · Cancel anytime
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.
FAQ
What kinds of tools can I add to Hermes?
Shell scripts, HTTP/API integrations, MCP servers, and custom Python plugins. Hermes ships 40+ built-in tools; these extend it to almost anything you can script or expose.
How do MCP servers fit in?
MCP servers connect Hermes to external tool providers (GitHub, databases, browsers, internal APIs) over a standard protocol. They're the cleanest way to add capability without writing a plugin from scratch.
Are custom tools a security risk?
They can be — tools run on your machine with the agent's access. Review what each tool can do, scope its permissions, and pair risky tools with Tirith approvals.