# Hermes MCP

Hermes MCP is a hosted MCP gateway for messaging, knowledge, and social connectors.

The production endpoint is:

```text
https://hermes.squaremcp.com/mcp
```

Hermes currently supports MCP access patterns for:

1. email
2. Obsidian vault notes
3. WhatsApp Business
4. LinkedIn
5. Telegram
6. additional social connectors that are in various states of credentialing and rollout

---

## What Hermes is for

Hermes is the integration and connector layer behind broader product work such as SquareMCP.

Use Hermes when you want:

1. an MCP endpoint that exposes real tools over Streamable HTTP
2. API-key or OAuth-protected access
3. connector access from agent clients such as Codex CLI, Claude Code, opencode, or ChatGPT

---

## Core transports

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

---

## Authentication

Hermes accepts:

1. `x-api-key` header
2. `?key=` query parameter
3. `Authorization: Bearer ...` for OAuth-based clients

For local/manual config examples in this repo, always substitute your own value for:

```text
YOUR_MCP_API_KEY
```

Do not commit live API keys into repo config files.

---

## Client setup guides

Use the setup guide that matches your client:

1. [Codex CLI setup](./CODEX_SETUP.md)
2. [CLI agent setup (Claude Code, generic MCP CLIs, Claude Desktop)](./AGENTS_CLI_SETUP.md)
3. [opencode setup](./OPENCODE.md)
4. [ChatGPT Custom GPT setup](./CHATGPT_SETUP.md)
5. [Social publishing setup (TikTok / Facebook)](./SOCIAL_PUBLISHING_SETUP.md)

---

## Codex quick setup

Add this block to `~/.codex/config.toml`:

```toml
[mcp_servers.hermes]
url = "https://hermes.squaremcp.com/mcp"
```

See [CODEX_SETUP.md](./CODEX_SETUP.md) for the full notes and caveats.

---

## opencode quick setup

Project-level `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hermes": {
      "type": "remote",
      "url": "https://hermes.squaremcp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_MCP_API_KEY"
      }
    }
  }
}
```

Full instructions: [OPENCODE.md](./OPENCODE.md)

---

## Local development

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

The local server runs on port `3456` by default.

---

## Deployment

Production deployment notes are in:

1. [DEPLOY.md](./DEPLOY.md)
2. `hermes-k8s.yaml`

SquareMCP product-site docs live under:

1. [`product/site`](./product/site)
2. [`product/README.md`](./product/README.md)
3. [`videos/remotion-demo`](./videos/remotion-demo/README.md) for SquareMCP video production assets and render workflows

---

## Notes

The historical docs in this repo started from an email-only Claude-focused setup. Current deployment and setup guidance should follow:

1. the `hermes.squaremcp.com` domain
2. Streamable HTTP `/mcp` as the default transport
3. the dedicated client setup docs linked above