# 🔌 Hermes MCP Server

> **Expose 100+ Hermes Agent skills to any MCP-compatible AI client.**
>
> Connect Claude Desktop, Cursor, Continue, Zed, or any MCP client to Hermes Agent's powerful toolkit.

[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue)](https://pypi.org/project/hermes-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Sponsor](https://img.shields.io/badge/Sponsor-❤️-pink?logo=github-sponsors)](https://github.com/sponsors/pangtongya)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green?logo=anthropic)](https://modelcontextprotocol.io)

---

## ✨ What You Get

Install one MCP server, get ALL these tools in your AI client:

| Category | Tools |
|----------|-------|
| 🌐 **Web** | Search, extract, navigate, scrape |
| 🖥️ **Browser** | Full headless browser — click, type, scroll, screenshot |
| 💻 **Terminal** | Execute shell commands, run Python code |
| 📁 **Files** | Read, write, search files (ripgrep-backed) |
| 🐙 **GitHub** | Repo info, search, create issues, manage PRs |
| 📚 **Research** | arXiv search, YouTube transcripts, blog monitoring |
| 📝 **Productivity** | Notion, Google Workspace, Linear, Airtable |
| 🎨 **Creative** | Image generation, ASCII art, diagrams, music |
| 🤖 **AI** | Full Hermes Agent reasoning — multi-step, tool-using |

---

## 🚀 Quick Start

### 1. Install

```bash
pip install hermes-mcp-server
```

### 2. Start Hermes Agent

```bash
# Start Hermes Agent with HTTP API enabled
hermes serve --http --port 8080
```

### 3. Configure your MCP client

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hermes": {
      "command": "hermes-mcp",
      "args": ["--endpoint", "http://localhost:8080"],
      "env": {
        "HERMES_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Cursor / Continue / Zed**:

```json
{
  "mcpServers": {
    "hermes": {
      "command": "hermes-mcp",
      "args": ["--endpoint", "https://your-hermes-instance.com"]
    }
  }
}
```

### 4. Restart your MCP client and start using Hermes tools!

---

## 📋 Complete Tool List

| Tool | Description |
|------|-------------|
| `web_search` | Google/Bing web search with snippets |
| `web_extract` | Extract clean content from any URL |
| `browser_navigate` | Headless browser navigation |
| `browser_snapshot` | Get page accessibility tree |
| `browser_click` | Click elements by ref ID |
| `terminal_exec` | Execute shell commands |
| `code_execute` | Run Python code with Hermes SDK |
| `file_read` | Read files with line numbers |
| `file_write` | Create/overwrite files |
| `file_search` | Ripgrep-powered file/content search |
| `github_repo_info` | Get GitHub repo details |
| `github_search_repos` | Search GitHub repos |
| `github_create_issue` | Create GitHub issues |
| `arxiv_search` | Search academic papers |
| `youtube_transcript` | Get YouTube transcripts |
| `notion_search` | Search Notion workspace |
| `image_generate` | AI image generation |
| `ai_complete` | Full Hermes Agent reasoning |

> 80+ more tools coming soon — all 100+ Hermes skills will be exposed.

---

## 🐳 Docker

```bash
docker run -e HERMES_ENDPOINT=http://host.docker.internal:8080 \
           ghcr.io/pangtongya/hermes-mcp-server:latest
```

---

## 💰 Monetization

Hermes MCP Server is **free and open-source**. Revenue comes from:

| Tier | Price | Includes |
|------|-------|----------|
| 🆓 **Community** | Free | Self-hosted, all tools, community support |
| ⭐ **Pro** | $5/mo | Priority support, hosted Hermes endpoint, 1000 req/day |
| 🏢 **Team** | $29/mo | 5 seats, hosted endpoint, 10000 req/day, Slack support |
| 🚀 **Enterprise** | Custom | Dedicated instance, SSO, SLA, unlimited requests |

**[Become a Sponsor →](https://github.com/sponsors/pangtongya)**

---

## 🏗️ Architecture

```
┌──────────────────┐     MCP Protocol     ┌──────────────────┐     HTTP      ┌──────────────────┐
│  Claude Desktop  │◄────────────────────►│  Hermes MCP       │◄────────────►│  Hermes Agent     │
│  Cursor / Zed    │   (stdio / JSON-RPC) │  Server           │   (REST API)  │  100+ Skills     │
│  Continue / etc  │                      │  (Python)         │              │  Tools + Models  │
└──────────────────┘                      └──────────────────┘              └──────────────────┘
```

---

## 🔧 Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `HERMES_ENDPOINT` | `http://localhost:8080` | Hermes Agent HTTP endpoint |
| `HERMES_API_KEY` | (none) | API key for authentication |

---

## 🛠️ Development

```bash
git clone https://github.com/pangtongya/hermes-mcp-server.git
cd hermes-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run locally
python -m hermes_mcp.cli --endpoint http://localhost:8080
```

---

## 📄 License

MIT © [pangtongya](https://github.com/pangtongya)

---

## ⭐ Star History

If this project helps you, please consider [sponsoring](https://github.com/sponsors/pangtongya) or giving it a ⭐!