hermes-mcp-server 3.0.1

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

Автор: XuViGaN

Self-hosted MCP (Model Context Protocol) gateway — bridges Android/Web clients to Hermes AI Agent. Разверни свой AI-сервер за 30 секунд.

Архитектура

┌──────────────────┐      ┌─────────────────────────┐      ┌──────────────────┐
│  Hermes Gateway  │      │   Hermes MCP Server      │      │  Hermes Agent    │
│  (Android App)   │◄────►│   (этот пакет)           │◄────►│  (hermes CLI)    │
│                  │ WS   │   Порт 8080              │ CLI  │                  │
│  • Чат           │ SSE  │   • MCP JSON-RPC 2.0     │      │  • LLM модели    │
│  • Стриминг      │ HTTP │   • SSE streaming        │      │  • Инструменты   │
│  • Файлы         │      │   • REST API             │      │  • Навыки        │
│  • Тёмная тема   │      │   • Управление сессиями  │      │  • Память        │
└──────────────────┘      └─────────────────────────┘      └──────────────────┘

Быстрый старт

Linux / macOS

# Рекомендуемый способ (Debian/Ubuntu):
pipx install hermes-mcp-server

# Или через pip (если не Debian):
pip install hermes-mcp-server

# На Debian/Ubuntu без pipx:
pip install --break-system-packages hermes-mcp-server

# Запуск
hermes-mcp-server

Если ошибка «externally-managed-environment» (Debian/Ubuntu)

Это PEP 668 — система защищает Python от случайной поломки. Три решения:

# 1. pipx (рекомендуется) — ставит в изолированное окружение
apt install pipx
pipx install hermes-mcp-server
hermes-mcp-server

# 2. --break-system-packages (быстро)
pip install --break-system-packages hermes-mcp-server

# 3. Виртуальное окружение
python3 -m venv hermes-env
source hermes-env/bin/activate
pip install hermes-mcp-server
hermes-mcp-server

Подключение с Android

1. Скачай Hermes Gateway APK
2. Открой → Add Profile
3. Введи IP своего сервера и порт 8080
4. Жми Connect — и общайся со своим ИИ!

Подключение из терминала

pip install hermes-mcp-client
hermes-mcp connect http://localhost:8080 --name local
hermes-mcp chat "Привет, Hermes!" --server local

Конфигурация

# Свой порт
hermes-mcp-server --port 9000

# Конкретная модель и провайдер
hermes-mcp-server --model deepseek-v4-pro --provider opencode-go

# Свой хост (для доступа из локальной сети)
hermes-mcp-server --host 0.0.0.0 --port 8080

# Полный список опций
hermes-mcp-server --help

Переменные окружения

Переменная	По умолчанию	Описание
HOST	0.0.0.0	Адрес сервера
PORT	8080	Порт
HERMES_PATH	hermes	Путь к бинарнику hermes
HERMES_HOME	~/.hermes	Домашняя папка Hermes
HERMES_MODEL	—	Модель по умолчанию
HERMES_PROVIDER	—	Провайдер по умолчанию
HERMES_UPLOAD_DIR	/tmp/hermes-uploads	Папка для загрузок

Endpoints

Метод	Путь	Описание
WS	/ws	MCP WebSocket (JSON-RPC 2.0)
GET	/stream	HTTP SSE стриминг чата
GET	/health	Health check
GET	/status	Полный статус сервера
POST	/chat	One-shot чат
POST	/upload	Загрузка файла
GET	/config/providers	Список провайдеров
GET	/config/models?provider=X	Список моделей
GET	/mcp/info	Информация о сервере + тулы
GET	/docs	Swagger UI (автодокументация)
GET	/	Welcome page

MCP Tools

Tool	Описание
hermes_chat	Отправить сообщение Hermes
hermes_status	Статус агента
hermes_execute	Выполнить shell-команду
hermes_analyze_file	Анализ файла
hermes_new_session	Новая сессия
hermes_send_file	Загрузить файл

Установка как 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 \
    --model deepseek-v4-pro \
    --provider opencode-go
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

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

Пример Docker-развёртывания

FROM python:3.11-slim
RUN pip install hermes-mcp-server hermes-agent
EXPOSE 8080
CMD ["hermes-mcp-server", "--host", "0.0.0.0", "--port", "8080"]

docker build -t hermes-mcp .
docker run -d -p 8080:8080 -v ~/.hermes:/root/.hermes hermes-mcp

Экосистема Hermes MCP

Компонент	PyPI	Описание
hermes-mcp-server	PyPI	MCP сервер (этот пакет)
hermes-mcp-client	PyPI	CLI клиент для терминала
Hermes Gateway	APK	Android приложение

# Полный флоу для self-hosting:
pip install hermes-mcp-server hermes-mcp-client
hermes-mcp-server --port 8080 &
hermes-mcp connect http://localhost:8080 --name my
hermes-mcp chat "Hello" --server my

Требования

• Python 3.10+
• Hermes Agent (pip install hermes-agent)
• Хотя бы один LLM-провайдер (API ключ в ~/.hermes/.env)

Лицензия

MIT — XuViGaN 2026