Metadata-Version: 2.4
Name: hermes-mcp-server
Version: 1.0.0
Summary: Hermes MCP Server — self-hosted gateway that bridges Android/Web clients to Hermes AI Agent via MCP (Model Context Protocol). WebSocket + HTTP SSE + REST.
Author-email: Gothbreach <gothbreach@hermes.dev>
License-Expression: MIT
Keywords: mcp,model-context-protocol,hermes,ai,server,gateway,fastapi,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: websockets>=13.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.12

# 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

```bash
# 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

```bash
# 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)

```bash
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:

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

## License

MIT — Gothbreach 2026
