# Hermes MCP — SquareMCP Gateway

Hermes is the MCP server powering [SquareMCP](https://squaremcp.com). It exposes 51 tools across 11 platforms (email, Obsidian, WhatsApp, LinkedIn, TikTok, Facebook, Instagram, Twitter, Telegram, Discord, Snapchat) over Streamable HTTP, with per-user authentication, OAuth 2.0, and multi-tenant credential isolation.

**Production endpoint:**
```
https://hermes.squaremcp.com/mcp
```

---

## Quick connect

### claude.ai
1. Settings → MCP Servers → Add → enter `https://hermes.squaremcp.com`
2. Complete the OAuth popup (login with your SquareMCP credentials)
3. Click "Connect MCP client"

### Claude Desktop
```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "squaremcp": {
      "type": "http",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Codex CLI
```toml
# ~/.codex/config.toml
[mcp_servers.squaremcp]
url = "https://hermes.squaremcp.com/mcp"
headers = { Authorization = "Bearer YOUR_TOKEN" }
```

### opencode
```json
{
  "mcp": {
    "squaremcp": {
      "type": "remote",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

Get your token from the [SquareMCP dashboard](https://app.squaremcp.com) → Connect MCP Client.

---

## Architecture

See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full architecture with diagrams.

```
                     nginx ingress (TLS)
                           │
              ┌────────────┼────────────┐
              │            │            │
        hermes-mcp    squaremcp-app  squaremcp-docs
        :3456          :8080          :80
        (MCP API)      (SaaS UI)     (Docs)
              │
    ┌─────────┼─────────┐
    │         │         │
  MySQL 8   Redis 7  /vaults
  (creds +  (cache +  (Obsidian)
  billing)   DLQ)
```

**Stack:** TypeScript / Node.js, Express, MySQL 8, Redis 7, MicroK8s, Docker
**Auth:** JWT session cookies + OAuth 2.0 PKCE + API key
**Platform clients:** 11 platforms, 51 MCP tools

---

## Platforms

| Platform | Tools |
|----------|-------|
| Email (IMAP/SMTP) | search, read, send, draft, folders |
| Obsidian | search, read, append, update, sync |
| WhatsApp Business | send, template, list templates |
| LinkedIn | profile, post, search connections, message, video |
| TikTok | profile, creator info, upload video, status |
| Facebook | page, posts, post, photo, video |
| Instagram | profile, media, post, reel |
| Twitter/X | profile, tweets, search, tweet, video |
| Telegram | me, send, photo, updates, chat |
| Discord | me, guilds, channels, send, messages |
| Snapchat | me, ad accounts, create snap |

---

## Authentication

Hermes accepts (in priority order):

1. `x-api-key` header — global superadmin or per-customer key
2. `Authorization: Bearer <token>` — JWT or OAuth access token
3. `Cookie: session=<JWT>` — web session (set by `/api/auth/login` or `/login`)

---

## Transports

| Transport | URL |
|-----------|-----|
| Streamable HTTP (preferred) | `https://hermes.squaremcp.com/mcp` |
| Legacy SSE | `https://hermes.squaremcp.com/sse` |

---

## Client setup guides

- [Codex CLI](./CODEX_SETUP.md)
- [Claude Code / CLI agents](./AGENTS_CLI_SETUP.md)
- [opencode](./OPENCODE.md)
- [ChatGPT Custom GPT](./CHATGPT_SETUP.md)
- [Social publishing (TikTok / Facebook)](./SOCIAL_PUBLISHING_SETUP.md)

---

## Local development

```bash
npm install
cp .env.example .env   # fill in credentials
npm run dev
curl http://localhost:3456/health
```

Server runs on port `3456` by default.

---

## Deployment

See [DEPLOY.md](./DEPLOY.md) for the full deployment runbook.

The short version:
```bash
npm run build
docker build -t localhost:32000/hermes-mcp:latest .
docker push localhost:32000/hermes-mcp:latest
# update sha256 digest in hermes-k8s.yaml
microk8s kubectl apply -f hermes-k8s.yaml
```