Files
mcps/README.md
T
2026-09-05 16:30:23 +02:00

3.6 KiB

MCP Servers: Gmail + Telegram

This repository contains two HTTP MCP servers:

  • Gmail MCP server in src/index.js
  • Telegram MCP server in src/telegram.js

Both expose MCP over Streamable HTTP at MCP_PATH (default /mcp) and include /health endpoint.

Setup

cd gmail-mcp-server
npm install
cp .env.example .env

Gmail server

Run locally:

node src/index.js

Required env:

  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
  • GOOGLE_REFRESH_TOKEN
  • GMAIL_TO_ALLOWLIST

Tools:

  • list_messages
  • get_message

Security behavior:

  • Query is automatically constrained with allowlist recipients.
  • Returned messages are post-filtered against message headers.
  • get_message denies access if recipients are outside allowlist.

Telegram server

Run locally:

node src/telegram.js

Required env:

  • TELEGRAM_BOT_TOKEN
  • TELEGRAM_CHAT_ID

Optional env:

  • TELEGRAM_POLLING_INTERVAL_MS (default 1000)
  • TELEGRAM_REQUEST_TTL_SECONDS (default 600)
  • HTTP_HOST (default 127.0.0.1)
  • PORT (default 3000)
  • MCP_PATH (default /mcp)
  • ENV_FILE (default /run/secrets/telegram-secrets)

Telegram behavior:

  • Configured for one bot and one chat room.
  • Sends text messages with optional image by URL or local file path.
  • Sends inline callback buttons.
  • Receives and stores button click responses.
  • Supports send-and-expect-reply flow using async request IDs.

Telegram tools:

  • send_message
  • send_message_with_buttons
  • send_message_with_buttons_blocking
  • send_message_expect_reply
  • send_message_expect_reply_blocking
  • get_request_result
  • cancel_request
  • wait_for_request_result

Async request flow (buttons and replies)

  1. Call send_message_with_buttons or send_message_expect_reply.
  2. Tool returns request_id.
  3. User clicks a button or replies in Telegram.
  4. Call get_request_result with request_id to fetch status and payload.
  5. Optional: call cancel_request to cancel pending request.

Blocking alternative:

  • Call wait_for_request_result with request_id to block until request completes or timeout.
  • Or call send_message_with_buttons_blocking to send buttons and wait for a click in a single blocking tool call.
  • Or call send_message_expect_reply_blocking to send and wait for reply in a single blocking tool call.

Docker

  • Gmail image uses Dockerfile.
  • Telegram image uses Dockerfile.telegram.
  • Compose includes both services: gmail-mcp-server and telegram-mcp-server.

Validate compose:

docker compose config

Docker secret examples

Gmail:

docker service scale gmail_mcp_gmail-mcp-server=0
docker service update --secret-rm gmail-secrets gmail_mcp_gmail-mcp-server
docker secret rm gmail-secrets
printf \
"GOOGLE_CLIENT_ID=\n\
GOOGLE_CLIENT_SECRET=\n\
GOOGLE_REFRESH_TOKEN=\n\
GMAIL_USER=me\n\
GMAIL_TO_ALLOWLIST=alerts@example.com,ops@example.com\n\
GMAIL_DEFAULT_MAX_RESULTS=20\n" | \
docker secret create gmail-secrets -
docker service update --secret-add gmail-secrets gmail_mcp_gmail-mcp-server
docker service scale gmail_mcp_gmail-mcp-server=1

Telegram:

docker service scale gmail_mcp_telegram-mcp-server=0
docker service update --secret-rm telegram-secrets gmail_mcp_telegram-mcp-server
docker secret rm telegram-secrets
printf \
"TELEGRAM_BOT_TOKEN=\n\
TELEGRAM_CHAT_ID=\n\
TELEGRAM_POLLING_INTERVAL_MS=1000\n\
TELEGRAM_REQUEST_TTL_SECONDS=600\n" | \
docker secret create telegram-secrets -
docker service update --secret-add telegram-secrets gmail_mcp_telegram-mcp-server
docker service scale gmail_mcp_telegram-mcp-server=1