Hermes MCPs

Personal WhatsApp + Telegram MCP servers for AI agents (hermes-agent, Claude, and any MCP client)

Documentation • Installation • Configuration • 🤖 Agent Setup • 🪽 Hermes Setup • Tools Reference

🚀 What is Hermes MCPs?

Two sibling MCP servers that give an AI agent control of the owner's personal messaging accounts, built on one shared TypeScript core:

• WhatsApp (dist/index.js, 84 waha_* tools) — via WAHA (WhatsApp HTTP API) on the GOWS engine

• Telegram (dist/telegram/index.js, 15 tg_* tools) — directly over MTProto via gramjs, no bot API

Both share the same agent-grade design: inbox triage, LLM-ready conversation rendering, inline voice-note transcription (Soniox), compact token-efficient output, and self-explanatory errors.

✨ Key Features

• 📱 Complete WhatsApp Control - Send/receive messages, manage chats, create groups

• 🎯 84 Tools - Comprehensive API coverage for sessions, messaging, contacts, groups, status, labels, and interactive workflows

• 🧠 Agent-Grade Compound Tools - waha_inbox (triage), waha_find_chat (name → chatId), waha_reply (human-like answering), waha_get_chat_context (LLM-ready conversation rendering)

• 🎙️ Voice Transcription - Incoming voice notes transcribed automatically via Soniox (Hebrew + 60 languages, OGG/Opus native) — verified end-to-end on real speech

• 🔄 Smart Media Handling - Auto-conversion for voice/video, URLs & local files, inline image viewing for vision models

• 🤖 AI-Native - Token-efficient compact responses, MCP tool annotations (read-only/destructive hints)

• 🔒 Secure - Environment-based API key management, optional local-file sandbox (WAHA_MCP_FILES_DIR)

• ⚡ Fast & Reliable - TypeScript-powered, request timeouts, typed errors, vitest suite

• 🔔 Event-Driven Chat Watches - WAHA webhooks wake Hermes only for watched chats; no minute-level polling. See docs/event-driven-chat-watches.md

• ✈️ Telegram too - a second MCP server (dist/telegram/index.js) controls your personal Telegram account over MTProto: 15 tg_* tools sharing the same core (inbox digest, conversation rendering, voice transcription, send/react/edit, media, search). See Telegram server

Related MCP server: OpenWA MCP Server

📋 Prerequisites

Before you begin, ensure you have:

• Node.js 18+ - Download here

• WAHA Plus on the GOWS engine, running in Docker - required for media (the basis of transcription & image viewing) and for connection stability. Full server setup → docs/waha-server-setup.md

• WAHA API Key - any strong secret you set via WHATSAPP_API_KEY

• (optional) Soniox API key - enables voice-note transcription (soniox.com; Hebrew + 60 languages)

Why Plus + GOWS? Core can't download incoming media (no voice transcription, no image viewing). NOWEB/WEBJS get the device force-unlinked or break on WhatsApp updates. The setup guide explains the tradeoffs and the anti-ban configuration in detail.

🛠️ Installation

1. Clone & Install

git clone https://github.com/dudu1111685/hermes_mcps.git
cd waha-mcp
npm install
npm run build

2. Set Environment Variables

Create a .env file or export variables:

export WAHA_API_KEY="your-api-key-here"
export WAHA_URL="http://localhost:3001"         # Optional, defaults to localhost:3001
export WAHA_DEFAULT_SESSION="default"           # Optional — see Session policy below
export SONIOX_API_KEY="your-soniox-key"         # Optional — enables voice note transcription
export WAHA_TIMEOUT_MS="30000"                  # Optional — WAHA request timeout
export WAHA_MCP_FILES_DIR="/tmp/waha-mcp"       # Optional — restrict local-file reads to this dir
export WAHA_THROTTLE=1                          # Optional — enable anti-ban send pacing (off by default)

Session policy: WAHA_DEFAULT_SESSION sets the default session name for every tool call. Set it to your session name (e.g. default) for a single-account setup. If you leave it unset, the session parameter becomes required on every tool call — the safe choice when multiple WhatsApp accounts are connected, since a silent default could send from the wrong account. Call waha_list_sessions to enumerate available sessions.

Anti-ban throttle: off by default since the GOWS engine fixed device_removed disconnects. Set WAHA_THROTTLE=1 to enable pacing (3–8s jitter between sends, max 8/min, group ops spaced 120s). High-volume or bursty sends to many recipients are still risky regardless of engine — enable throttling for those use cases.

⚙️ Configuration

Claude Desktop

Add to claude_desktop_config.json:

Linux: ~/.config/claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_URL": "http://localhost:3001",
        "WAHA_DEFAULT_SESSION": "default"
      }
    }
  }
}

Session note: WAHA_DEFAULT_SESSION makes every tool default to that session. Omit it only if you connect multiple WhatsApp accounts and want the tool to require an explicit session on every call.

Cline / VS Code

Add to your Cline MCP settings (~/.vscode/mcp.json or workspace settings):

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_DEFAULT_SESSION": "default"
      }
    }
  }
}

AI Agents (hermes-agent, Claude Code, and more)

🤖 Enable truly autonomous AI workflows:

Instead of the agent stopping when it needs user input, it can ask questions via WhatsApp and continue working!

🚀 Setup guides: AGENT_SETUP.md (Claude Code / generic MCP) • HERMES_SETUP.md (hermes-agent)

Quick config example:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/path/to/waha-mcp/dist/index.js"],
      "env": {
        "WAHA_API_KEY": "your-key",
        "WAHA_DEFAULT_SESSION": "default",
        "USER_WHATSAPP_CHAT_ID": "1234567890@c.us"
      }
    }
  },
  "globalInstructions": "When you need user input during development, send the question with waha_ask_user and poll waha_check_replies every ~30-60s until answered. Never stop and wait for manual console input."
}

How it works:

1. Claude hits a question → asks via WhatsApp

2. You reply from your phone

3. Claude continues working immediately

4. Zero downtime! ⚡

📖 See also:

• AGENT_SETUP.md - Setup + the ask/check-replies pattern for any MCP agent

• HERMES_SETUP.md - hermes-agent: config.yaml, tool selection, autonomy patterns

• skills/whatsapp-assistant/ - WhatsApp behavioral playbook skill (agentskills.io format)

• skills/event-driven-whatsapp-watches/ - bounded WAHA webhook watches that resume the exact opening Hermes session

• skills/telegram-assistant/ - Telegram behavioral playbook skill

Other MCP Clients

Use the mcporter CLI for quick testing:

mcporter call 'waha-mcp.waha_list_sessions()'
mcporter call 'waha-mcp.waha_send_text(chatId: "1234567890@c.us", text: "Hello from MCP!")'

🧰 Tools Reference

📂 Categories

📤 Media Upload Features:

• ✅ Local files & URLs supported

• ✅ Auto MIME type detection

• ✅ Auto video/voice conversion to WhatsApp format

• ✅ 50+ file types supported

• ✅ Base64 encoding handled automatically

Note: WAHA has no chat-level pin/mute endpoints, so no pin/mute chat tools are exposed (message pinning is available via waha_pin_message).

Use Case Example:

// Claude Code is building a feature and needs clarification
const q = await waha_ask_user({
  question: "Should I use REST or GraphQL for the API?",
  chatId: "1234567890@c.us"
});
// ...continue other work, then periodically:
const replies = await waha_check_replies({
  chatId: "1234567890@c.us",
  sinceTimestamp: q.sinceTimestamp,
  questionMessageId: q.questionMessageId
});
// User replied from phone: "Use GraphQL" → continue with GraphQL

Why non-blocking? The old blocking design waited up to 60 minutes inside one tool call — every MCP client times out long before that. The new pair lets the agent keep working and poll on its own schedule. Quoted replies to the question are detected reliably (including in groups via the fromUser filter).

🔒 Security Note: Local File Access

Send tools that accept a local file path (waha_send_image, waha_send_file, waha_send_voice, status tools, etc.) can read any file the server process can access. Since chat content (including voice transcripts) from other people reaches the agent, a prompt-injected instruction could try to exfiltrate local files (e.g. SSH keys) by "sending" them.

To restrict reads to a single directory, set the WAHA_MCP_FILES_DIR environment variable (e.g. to /tmp/waha-mcp, where waha_get_media saves downloads). Paths outside it are then rejected. When unset, any local path is allowed.

📚 Chat ID Formats

Understanding WhatsApp ID formats:

Note: Phone numbers should exclude the + prefix.

🎯 Quick Examples

Send a Text Message

mcporter call 'waha-mcp.waha_send_text(
  chatId: "1234567890@c.us",
  text: "Hello from WAHA MCP!"
)'

Send an Image from URL

mcporter call 'waha-mcp.waha_send_image(
  chatId: "1234567890@c.us",
  imageUrl: "https://example.com/photo.jpg",
  caption: "Check this out!"
)'

Create a Group & Add Participants

# Create group
mcporter call 'waha-mcp.waha_create_group(
  name: "Team Chat",
  participants: ["1111111111@c.us", "2222222222@c.us"]
)'

# Add more participants
mcporter call 'waha-mcp.waha_add_group_participants(
  chatId: "{group_id}@g.us",
  participants: ["3333333333@c.us"]
)'

List All Chats

mcporter call 'waha-mcp.waha_list_chats()'

✈️ Telegram Server

The repo ships a second, independent MCP server that operates your personal Telegram account directly over MTProto (via gramjs) — no bot, no Telegram Bot API limits. It reuses the same core layer as the WhatsApp server (tool wrapper, compact formatting, Soniox voice transcription).

Setup

# 1. Get api_id + api_hash at https://my.telegram.org → "API development tools"
# 2. One-time interactive sign-in (phone → code → optional 2FA password).
#    Writes TELEGRAM_API_ID / TELEGRAM_API_HASH / TELEGRAM_SESSION into .env:
npm run telegram:login

⚠️ TELEGRAM_SESSION grants full access to the account — treat it like a password and only pass it via environment configuration.

MCP client config

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp/dist/telegram/index.js"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "...",
        "TELEGRAM_SESSION": "...",
        "SONIOX_API_KEY": "..."
      }
    }
  }
}

Tools (15, prefixed tg_)

chat accepts what tg_list_chats returns: a numeric id (channels use the -100… form), @username, a +phone of a contact, or me (Saved Messages).

🧪 Development

Run in Watch Mode

npm run dev  # Recompiles on file changes

Run Tests

npm test

Build for Production

npm run build

📖 Documentation

For detailed documentation, see the docs folder:

• Session Management

• Messaging Guide

• Group Management

• Media Handling

• Troubleshooting

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• WAHA (WhatsApp HTTP API) - The backbone of this integration

• Model Context Protocol - Enabling AI-native tool integration

• Anthropic - For Claude Desktop and MCP SDK

Built with ❤️ for the MCP community

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature