Files
2026-09-05 16:30:23 +02:00

159 lines
3.6 KiB
Markdown

# 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
```