Hermes MCPs

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

License: MIT Node.js Version MCP Compatible TypeScript

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
• ✈️ 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

📋 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": "[email protected]"
      }
    }
  },
  "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/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: "[email protected]", text: "Hello from MCP!")'

🧰 Tools Reference

📂 Categories

// 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: "[email protected]"
});
// ...continue other work, then periodically:
const replies = await waha_check_replies({
  chatId: "[email protected]",
  sinceTimestamp: q.sinceTimestamp,
  questionMessageId: q.questionMessageId
});
// User replied from phone: "Use GraphQL" → continue with GraphQL

🔒 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: "[email protected]",
  text: "Hello from WAHA MCP!"
)'

Send an Image from URL

mcporter call 'waha-mcp.waha_send_image(
  chatId: "[email protected]",
  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: ["[email protected]", "[email protected]"]
)'

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

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