forked from admin/mcps
159 lines
3.6 KiB
Markdown
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
|
|
```
|