Support Codex OAuth login and add CLI setup docs
This commit is contained in:
Garfield
210
README.md
210
README.md
@@ -1,129 +1,141 @@
|
||||
# Hermes MCP
|
||||
|
||||
A multi-account email MCP server for [Claude AI](https://claude.ai).
|
||||
Supports **Yahoo Mail** (IMAP App Password) and any **self-hosted mail server** (IMAP/SMTP).
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
## What Hermes is for
|
||||
|
||||
- Read, search, and send email from Claude via MCP
|
||||
- Multi-account support: Yahoo Mail and custom IMAP/SMTP servers
|
||||
- Streamable HTTP transport (MCP 1.x) + legacy SSE endpoint
|
||||
- Automatic session recovery after server restarts
|
||||
- Docker and Kubernetes deployment ready
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
## Core transports
|
||||
|
||||
| Tool | Description | Key params |
|
||||
|------|-------------|------------|
|
||||
| `get_profile` | Get email address for an account | `account` |
|
||||
| `search_messages` | Search INBOX by keyword / sender / subject | `q`, `maxResults`, `account` |
|
||||
| `read_message` | Read full message body by UID | `uid`, `account` |
|
||||
| `list_folders` | List all mailbox folders | `account` |
|
||||
| `create_draft` | Save a draft to the Drafts folder | `to`, `subject`, `body`, `account` |
|
||||
| `send_email` | Send an email | `to`, `subject`, `body`, `account` |
|
||||
|
||||
`account` parameter allows you to specify which configured mailbox to use (defaults to `"yahoo"`).
|
||||
| Transport | URL |
|
||||
|----------|-----|
|
||||
| Streamable HTTP (preferred) | `https://hermes.squaremcp.com/mcp` |
|
||||
| Legacy SSE | `https://hermes.squaremcp.com/sse` |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (local dev)
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
# 1. Install dependencies
|
||||
npm install
|
||||
|
||||
# 2. Configure credentials
|
||||
cp .env.example .env
|
||||
# Edit .env with your email credentials
|
||||
|
||||
# 3. Run in dev mode
|
||||
npm run dev
|
||||
|
||||
# 4. Verify
|
||||
curl http://localhost:3456/health
|
||||
# → {"status":"ok","service":"hermes-mcp"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Copy `.env.example` to `.env` and fill in your values:
|
||||
|
||||
```env
|
||||
# Yahoo Mail — generate an App Password at:
|
||||
# https://myaccount.yahoo.com/security → App passwords
|
||||
YAHOO_EMAIL=you@yahoo.com
|
||||
YAHOO_APP_PASSWORD=xxxx xxxx xxxx xxxx
|
||||
|
||||
# Optional: Self-hosted mail server (any IMAP/SMTP server)
|
||||
# CUSTOM_EMAIL=you@yourdomain.com
|
||||
# CUSTOM_PASSWORD=yourpassword
|
||||
# CUSTOM_IMAP_HOST=mail.yourdomain.com
|
||||
# CUSTOM_IMAP_PORT=993
|
||||
# CUSTOM_SMTP_HOST=mail.yourdomain.com
|
||||
# CUSTOM_SMTP_PORT=587
|
||||
|
||||
PORT=3456
|
||||
```
|
||||
The local server runs on port `3456` by default.
|
||||
|
||||
---
|
||||
|
||||
## Connecting to Claude.ai
|
||||
## Deployment
|
||||
|
||||
1. Go to **Claude.ai → Settings → Connectors → Add custom connector**
|
||||
2. Enter your server URL: `https://your-domain.com/mcp`
|
||||
3. Click **Connect**
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment (Kubernetes)
|
||||
## Notes
|
||||
|
||||
See [`DEPLOY.md`](./DEPLOY.md) for full instructions covering:
|
||||
The historical docs in this repo started from an email-only Claude-focused setup. Current deployment and setup guidance should follow:
|
||||
|
||||
- MicroK8s setup with nginx-ingress and cert-manager
|
||||
- Building and pushing a Docker image to the local registry
|
||||
- Applying the Kubernetes Deployment / Service / Ingress manifests
|
||||
- Zero-downtime redeploys after code changes
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Claude.ai ──POST /mcp──► StreamableHTTPServerTransport
|
||||
│
|
||||
┌─────────▼──────────┐
|
||||
│ MCP Server (SDK) │
|
||||
│ tools / handlers │
|
||||
└──┬──────────────┬───┘
|
||||
│ │
|
||||
imapflow (IMAP) nodemailer (SMTP)
|
||||
│ │
|
||||
┌────────▼───┐ ┌───────▼───────┐
|
||||
│ Yahoo Mail │ │ Custom IMAP/ │
|
||||
│ │ │ SMTP Server │
|
||||
│ │ │ (optional) │
|
||||
└────────────┘ └───────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Runtime:** Node.js + TypeScript
|
||||
- **MCP SDK:** `@modelcontextprotocol/sdk`
|
||||
- **IMAP:** `imapflow`
|
||||
- **SMTP:** `nodemailer`
|
||||
- **HTTP:** `express`
|
||||
- **Deployment:** Docker + MicroK8s
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
1. the `hermes.squaremcp.com` domain
|
||||
2. Streamable HTTP `/mcp` as the default transport
|
||||
3. the dedicated client setup docs linked above
|
||||
|
||||
Reference in New Issue
Block a user