Which integrations are available for this server?

Provides tools to list and retrieve email messages from Gmail, including search filtering and full message content with body.

How do I use Hermes Google MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hermes Google MCP Server list my calendar events for today" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Hermes Google MCP Server

by MAghadavoodi

Overview Schema Source Related Servers Discussions Admin

Python

Local

Hermes Google MCP Server

Schlanker MCP-Server für Google Workspace (Calendar · Gmail · Drive) — entwickelt für den Hermes Agent im Docker-Setup.

Warum dieses Projekt?

Die in der Hermes-Dokumentation beschriebenen drei Standard-Wege zur Google-Anbindung scheiterten im Docker-Container-Setup:

Weg	Problem
gws CLI MCP	`gws` v0.22.5 hat keinen `mcp`-Subbefehl
google_workspace_mcp	asyncio `TaskGroup`-Fehler beim Gateway-Connect
Google Remote MCP	OAuth-Flow im Container nicht möglich (kein Browser)

Dieser Server löst alle drei Probleme: Reines Python (stdlib-only), HTTP-Transport (umgeht den asyncio-Bug), nutzt die funktionierende gws-CLI-Authentifizierung.

v2.2.1 (Juli 2026): Gmail Body-Truncation-Limit (body_text[:5000]) entfernt — lange E-Mails (z.B. Medium Daily Digest mit 15+ Artikeln) werden jetzt vollständig gelesen, ohne dass Inhalte abgeschnitten werden. main()-Funktion mit if __name__-Guard ermöglicht Unit-Tests via import server.

Related MCP server: gg-mcp

Architektur

Hermes Gateway (Docker)         Host (masoud)
─────────────────────────       ─────────────────────────
config.yaml:                    ┌──────────────────────┐
  gws-mcp:                      │ gws-mcp Container    │
    url: http://172.17.0.1 ───► │  http_server.py      │
    :8777/mcp                   │  :8777 → server.py   │
                                │      → gws CLI       │
                                │      → Google APIs   │
                                └──────────────────────┘
                                  ▲ Port 8777 (forwarded)
                                  ▼
                          Google Workspace APIs
                          (Calendar v3 · Gmail v1 · Drive v3)

Container-Resilienz

Der Docker-Container ist gegen Port-Konflikte und unsauberes Herunterfahren abgesichert:

Maßnahme	Ort	Wirkung
`init: true`	`docker-compose.yml`	Tini als Init-Prozess — fängt Signale korrekt ab, verhindert Zombie-Prozesse
`stop_grace_period: 10s`	`docker-compose.yml`	10 Sekunden für sauberes Herunterfahren vor SIGKILL
`signal.signal(SIGTERM, ...)`	`http_server.py`	Schließt den HTTP-Socket bei Docker-Stop — Port sofort frei
`restart: unless-stopped`	`docker-compose.yml`	Container startet nach Crash oder Reboot automatisch neu

Ablauf bei docker stop / Reboot:

Docker sendet SIGTERM an den Container
http_server.py fängt das Signal und ruft server.server_close() auf
Port 8777 wird sofort freigegeben — kein Port-Konflikt beim Neustart
Container beendet mit Exit-Code 0 (statt 137/SIGKILL)
Nach Reboot startet Docker den Container automatisch (unless-stopped)

Manuelle Fehlerbehebung (falls Container im Status Exited (137) hängt):

docker start gws-mcp

Attachments & Pfadübersetzung

gws_gmail_send_message unterstützt Dateianhänge per MIME-Multipart. Da unterschiedliche MCP-Clients verschiedene Pfadformate übergeben, übersetzt der Server automatisch:

Quelle	Pfadbeispiel	Container-Pfad
Hermes TUI (Docker)	`/opt/data/workspace/report.pdf`	`/workspace/report.pdf`
OpenCode (Host)	`/home/masoud/.../workspace/report.pdf`	`/workspace/report.pdf`

Funktionsweise (server.py Zeile 176–183):

# 1. Hermes Docker-Pfad: /opt/data/workspace/ → /workspace/
p = p.replace("/opt/data/workspace/", "/workspace/")

# 2. Host-Pfad (OpenCode & Co.): Extrahiere alles ab /workspace/
parts = p.split("/workspace/", 1)
if len(parts) == 2:
    p = "/workspace/" + parts[1]

Voraussetzung: Der Workspace ist als Volume in den Container eingehängt (docker-compose.yml → ~/Development/HermesProject/hermes-data/workspace:/workspace).

Argument-Größenlimit (E2BIG)

Beim Senden großer Anhänge (>100 KB) würde die base64-kodierte MIME-Nachricht das Linux-Arg-Limit von 128 KB pro Argument überschreiten ([Errno 7] Argument list too long).

Lösung: Statt --json {"raw":"<base64>"} wird die MIME-Nachricht in eine Temp-Datei geschrieben und via --upload-Flag an gws übergeben – die Gmail API verarbeitet sie als multipart/upload (message/rfc822).

# MIME-Nachricht in Temp-Datei im cwd (/app) schreiben
tf = NamedTemporaryFile(suffix=".eml", delete=False, dir=".")
tf.write(mime_bytes)
tf.close()

# Statt --json mit inline-base64 → --upload mit Temp-Datei
run_gws(["gws","gmail","users","messages","send",
         "--params", '{"userId":"me"}',
         "--upload", os.path.basename(tf.name),
         "--upload-content-type", "message/rfc822"])
os.unlink(tf.name)

Tools

Tool	Dienst	CRUD	Beschreibung
`gws_calendar_list_events`	Calendar	READ	Events auflisten (Zeitraum, max. Anzahl)
`gws_calendar_create_event`	Calendar	CREATE	Termin erstellen mit Teilnehmern
`gws_calendar_update_event`	Calendar	UPDATE	Termin ändern
`gws_calendar_delete_event`	Calendar	DELETE	Termin löschen
`gws_gmail_list_messages`	Gmail	READ	E-Mail-IDs auflisten (Suchfilter)
`gws_gmail_get_message`	Gmail	READ	E-Mail-Inhalt + Body (includeBody=true, keine Truncation)
`gws_gmail_send_message`	Gmail	CREATE	E-Mail senden mit Anhängen (MIME)
`gws_gmail_delete_message`	Gmail	DELETE	E-Mail in Papierkorb verschieben
`gws_drive_list_files`	Drive	READ	Dateien/Ordner auflisten
`gws_drive_get_file`	Drive	READ	Datei-Metadaten abrufen
`gws_drive_create_file`	Drive	CREATE	Datei erstellen/hochladen
`gws_drive_update_file`	Drive	UPDATE	Datei ändern/ersetzen
`gws_drive_delete_file`	Drive	DELETE	Datei permanent löschen
`gws_drive_download_file`	Drive	READ	Datei herunterladen → workspace/

Voraussetzungen

gws CLI (npm install -g @googleworkspace/cli)
OAuth 2.0 Desktop-Client (Google Cloud Console → Credentials)
Authentifizierung via gws auth login

Deployment

Der Server läuft als Docker-Container mit systemd-Integration für automatischen Start nach Reboot.

Docker Compose

# 1. Projekt klonen
git clone https://github.com/MAghadavoodi/HermesGoogleMCP.git ~/Development/Google_MCP
cd ~/Development/Google_MCP

# 2. Container bauen & starten
docker compose up -d gws-mcp

# 3. Status prüfen
docker ps --filter name=gws-mcp

systemd-Service (automatischer Start)

# Service aktivieren (startet Container bei Login)
systemctl --user enable --now gws-mcp.service

# Service verwalten
systemctl --user status gws-mcp
systemctl --user stop gws-mcp
systemctl --user start gws-mcp

Die systemd-Unit delegiert an Docker (docker start/docker stop).
Die restart: unless-stopped-Policy im Container stellt sicher, dass er bei Crash oder Reboot automatisch neu startet.

Hermes-Konfiguration

In hermes-data/config.yaml:

mcp_servers:
  gws-mcp:
    url: http://172.17.0.1:8777/mcp
    enabled: true

platform_toolsets:
  cli:
  - gws-mcp
  matrix:
  - gws-mcp

Tests

# Unit-Tests (ohne Auth, kein gws CLI nötig)
python3 -m pytest tests/test_gmail_body_truncation.py -v

# Integration-Tests (benötigen gws auth)
python3 tests/test_calendar.py   # Calendar CRUD
python3 tests/test_gmail.py      # Gmail CRUD
python3 tests/test_drive.py      # Drive CRUD
python3 tests/test_all_crud.py   # Full CRUD integration

Projektstruktur

Google_MCP/
├── src/
│   ├── server.py          # MCP JSON-RPC Engine (CRUD + Attachments)
│   └── http_server.py     # HTTP-Wrapper (Port 8777, SIGTERM-Handler)
├── tests/
│   ├── test_gmail_body_truncation.py  # Unit-Tests: Body-Truncation (kein Limit)
│   ├── test_calendar.py
│   ├── test_gmail.py
│   ├── test_drive.py
│   └── test_all_crud.py
├── docs/
│   └── ARCHITECTURE.md    # Detaillierte Architektur-Doku
├── Dockerfile             # Docker-Image (ubuntu:24.04 + gws CLI)
├── docker-compose.yml     # Docker Compose (init, stop_grace_period)
├── requirements.txt       # stdlib-only, keine pip-Abhängigkeiten
└── .gitignore

Lizenz

MIT — siehe LICENSE

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

google-mcp
io.github.matiasbattocchia
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Calendar Management Cloud Platforms Workplace & Productivity
25
CalendarMCP
ai.calendarmcp
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Calendar Management Workplace & Productivity
21
ToolforestOAuth
io.toolforest
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Workplace & Productivity Health & Wellness Finance
2
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

google-workspace-mcp-server
Workplace & Productivity Email Calendar Management
EveryInc
A
license
A
quality
D
maintenance
MCP server for Google Workspace APIs - Docs, Sheets, Drive, Gmail, and Calendar. Enables reading, creating, and editing Google Docs and Sheets, managing comments, reading emails, and viewing calendar events.
Updated 6 months ago (2026-03-10 10:22 UTC)
34
21 npm
17
MIT
gg-mcp
Workplace & Productivity Email Calendar Management
tannht
A
license
B
quality
D
maintenance
A Model Context Protocol (MCP) server that connects AI agents to Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, and Slides).
Updated 6 months ago (2026-03-16 15:05 UTC)
30
2
MIT
google-workspace-mcp-advanced
Workplace & Productivity Communication
Skeptomenos
A
license
B
quality
D
maintenance
Production-ready MCP server for Google Workspace providing broad coverage across Gmail, Drive, Calendar, Docs, Sheets, and more, with safe-by-default write operations and markdown-to-Google-Docs support.
Updated 3 months ago (2026-06-11 17:15 UTC)
100
24 PyPI
MIT
gg-workspace-mcp
Workplace & Productivity Email Calendar Management
tannht
A
license
Not graded
quality
C
maintenance
A lightweight MCP server for managing Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Slides) through natural language with AI assistants like Claude and Cursor.
Updated 6 months ago (2026-03-19 03:53 UTC)
12 npm
1
MIT

Hermes Google MCP Server

Warum dieses Projekt?

Architektur

Container-Resilienz

Attachments & Pfadübersetzung

Argument-Größenlimit (E2BIG)

Tools

Voraussetzungen

Deployment

Docker Compose

systemd-Service (automatischer Start)

Hermes-Konfiguration

Tests

Projektstruktur

Lizenz

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

google-workspace-mcp-server

gg-mcp

google-workspace-mcp-advanced

gg-workspace-mcp