forked from admin/mcps
3.6 KiB
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_IDGOOGLE_CLIENT_SECRETGOOGLE_REFRESH_TOKENGMAIL_TO_ALLOWLIST
Tools:
list_messagesget_message
Security behavior:
- Query is automatically constrained with allowlist recipients.
- Returned messages are post-filtered against message headers.
get_messagedenies access if recipients are outside allowlist.
Telegram server
Run locally:
node src/telegram.js
Required env:
TELEGRAM_BOT_TOKENTELEGRAM_CHAT_ID
Optional env:
TELEGRAM_POLLING_INTERVAL_MS(default1000)TELEGRAM_REQUEST_TTL_SECONDS(default600)HTTP_HOST(default127.0.0.1)PORT(default3000)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_messagesend_message_with_buttonssend_message_with_buttons_blockingsend_message_expect_replysend_message_expect_reply_blockingget_request_resultcancel_requestwait_for_request_result
Async request flow (buttons and replies)
- Call
send_message_with_buttonsorsend_message_expect_reply. - Tool returns
request_id. - User clicks a button or replies in Telegram.
- Call
get_request_resultwithrequest_idto fetch status and payload. - Optional: call
cancel_requestto cancel pending request.
Blocking alternative:
- Call
wait_for_request_resultwithrequest_idto block until request completes or timeout. - Or call
send_message_with_buttons_blockingto send buttons and wait for a click in a single blocking tool call. - Or call
send_message_expect_reply_blockingto 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-serverandtelegram-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