hermes-mcp-server 1.0.0

Hermes MCP Server — self-hosted gateway that bridges Android/Web clients to Hermes AI Agent via MCP (Model Context Protocol). WebSocket + HTTP SSE + REST.

Hermes MCP Server

Self-hosted MCP (Model Context Protocol) gateway — bridges Android/Web clients to Hermes AI Agent. Run your own AI server in 30 seconds.

Architecture

┌──────────────────┐      ┌─────────────────────────┐      ┌──────────────────┐
│  Hermes Gateway  │      │   Hermes MCP Server      │      │  Hermes Agent    │
│  (Android App)   │◄────►│   (this package)         │◄────►│  (hermes CLI)    │
│                  │ WS   │   Port 8080              │ CLI  │                  │
│  • Chat          │ SSE  │   • MCP JSON-RPC         │      │  • LLM models    │
│  • Streaming     │ HTTP │   • SSE streaming        │      │  • Tools         │
│  • File upload   │      │   • REST API             │      │  • Skills        │
│  • Dark theme    │      │   • Session mgmt         │      │  • Memory        │
└──────────────────┘      └─────────────────────────┘      └──────────────────┘

Prerequisites

• Hermes Agent installed (pip install hermes-agent or https://github.com/NousResearch/hermes-agent)
• At least one LLM provider configured (API key in ~/.hermes/.env)
• Python 3.10+

Quick Start

# 1. Install
pip install hermes-mcp-server

# 2. Start
hermes-mcp-server

# That's it! Server running on http://0.0.0.0:8080

Connect from Android

1. Install Hermes Gateway APK on your phone
2. Open app → Add Profile
3. Enter your server's IP and port 8080
4. Press Connect — start chatting with your AI!

APK available at: https://github.com/gothbreach/hermes-gateway/releases

Configuration

# Custom port
hermes-mcp-server --port 9000

# Specific model + provider
hermes-mcp-server --model deepseek-v4-pro --provider opencode-go

# Custom host (for LAN access)
hermes-mcp-server --host 0.0.0.0 --port 8080

Environment Variables

Variable	Default	Description
HOST	0.0.0.0	Server bind address
PORT	8080	Server port
HERMES_PATH	hermes	Path to hermes binary
HERMES_HOME	~/.hermes	Hermes config directory
HERMES_MODEL	—	Default model override
HERMES_PROVIDER	—	Default provider override
HERMES_UPLOAD_DIR	/tmp/hermes-uploads	File upload directory

Endpoints

Method	Path	Description
WS	/ws	MCP WebSocket (JSON-RPC 2.0)
GET	/stream	HTTP SSE streaming chat
GET	/health	Health check
GET	/status	Full server status
POST	/chat	One-shot chat
POST	/upload	File upload
GET	/config/providers	List available providers
GET	/config/models?provider=X	List models for provider
GET	/mcp/info	MCP server info + tools
GET	/docs	Swagger UI

MCP Tools

Tool	Description
hermes_chat	Send message to Hermes
hermes_status	Get agent status
hermes_execute	Execute shell command
hermes_analyze_file	Analyze a file
hermes_new_session	Create new session
hermes_send_file	Upload file

Run as System Service (systemd)

cat > /etc/systemd/system/hermes-mcp.service << 'EOF'
[Unit]
Description=Hermes MCP Server
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/hermes-mcp-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now hermes-mcp

CLI Client

Use hermes-mcp-client to connect from terminal:

pip install hermes-mcp-client
hermes-mcp connect http://localhost:8080 --name local
hermes-mcp chat "Hello" --server local

License

MIT — Gothbreach 2026