# 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 ```bash cd gmail-mcp-server npm install cp .env.example .env ``` ## Gmail server Run locally: ```bash 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: ```bash 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: ```bash docker compose config ``` ## Docker secret examples Gmail: ```bash 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 ``` ```bash 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 - ``` ```bash docker service update --secret-add gmail-secrets gmail_mcp_gmail-mcp-server docker service scale gmail_mcp_gmail-mcp-server=1 ``` Telegram: ```bash 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 ``` ```bash 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 - ``` ```bash docker service update --secret-add telegram-secrets gmail_mcp_telegram-mcp-server docker service scale gmail_mcp_telegram-mcp-server=1 ```