Telegram Mcp Serverless

Private Telegram MCP server for Cloudflare Workers. It exposes a protected JSON-RPC MCP endpoint that can read Telegram dialogs/messages, search the local archive, send messages, store tags/contacts, and run background sync jobs without a permanent VPS process.

The repository contains only source code and templates. Do not commit Telegram sessions, API hashes, bearer tokens, Cloudflare tokens, .dev.vars, or your real wrangler.toml.

Why Cloudflare Workers

A traditional VPS runs a server all the time. You pay for an always-on machine, patch the OS, keep Node running, configure systemd, watch disk, rotate logs, and handle restarts.

Cloudflare Workers work differently: the Worker starts when an HTTP request, Cron event, or Queue event arrives. When there is no traffic, there is no permanent app process to keep alive. Cloudflare runs the isolate close to the edge, handles HTTPS, scaling, restarts, and deployment.

This is useful for a private MCP server because traffic is usually bursty: an agent asks for Telegram data, the Worker wakes up, opens/uses the Telegram MTProto session, answers, persists state, and stops consuming runtime after the request ends.

Architecture

Request flow:

1. MCP client sends HTTPS JSON-RPC request to /mcp.
2. Worker checks Authorization: Bearer <token> against MCP_BEARER_TOKEN stored in Cloudflare secrets.
3. Worker dispatches tools/list, initialize, or tools/call.
4. Live Telegram tools use mtcute over MTProto from inside the Worker.
5. Archive/control-plane data is stored in D1.
6. Telegram session/cache state is stored in KV and mirrored to D1.
7. Cron triggers every 15 minutes and enqueues sync ticks through Cloudflare Queues.

Storage:

• D1: dialogs, messages, FTS index, tags, contacts, sync jobs, session mirror, small media/cache objects.
• KV: current Telegram session/cache state and small cache objects.
• Queues: background sync requests.
• Cron: periodic wake-up for sync scheduling.
• Cloudflare secrets: Telegram API ID/hash, exported Telegram session, MCP bearer token.

R2 is not required for the core server. If you later want large media storage, R2 can be added as an optional binding.

Tools exposed

• listChannels — list live Telegram dialogs.
• messagesLive — fetch live messages from Telegram.
• messagesList — read archive or fetch live and persist to D1.
• messagesSearch — search archived messages with D1 FTS.
• messagesContext — read messages around an archived message.
• messagesSend — send a Telegram text message.
• topicsList — list Telegram forum topics when the peer is a forum.
• groupsMembersList — list group/channel members.
• scheduleMessageSync — enqueue a sync job.
• setChannelTags, listChannelTags — store and read channel tags.
• contactsAliasSet, contactsNotesSet, contactsSearch — local contact metadata.
• mediaPutTest — write/read a small object via D1/KV.
• telegramRuntimeStatus — show runtime configuration without secrets.

Security model

All POST requests to /mcp require a bearer token. Without the correct token, the Worker returns 401 unauthorized and does not expose tools or Telegram data.

Public endpoints:

• /healthz returns a simple health JSON without private data.
• GET /mcp returns a plain text endpoint marker without private data.

Private endpoints:

• POST /mcp requires Authorization: Bearer <MCP_BEARER_TOKEN>.

Recommended production hardening:

• Use a long random MCP bearer token.
• Keep all secrets in Cloudflare Worker secrets.
• Do not put secrets in wrangler.toml, README, tests, or logs.
• Rotate the Telegram session if it is ever leaked.
• Optionally restrict access with Cloudflare Access, WAF rules, or IP allowlists.

Setup

Install dependencies:

npm install

Login to Cloudflare:

npx wrangler login

Create Cloudflare resources:

npx wrangler d1 create telegram-mcp-serverless-db
npx wrangler kv namespace create SESSIONS
npx wrangler queues create telegram-mcp-serverless-sync

Copy the template config:

cp wrangler.example.toml wrangler.toml

Edit wrangler.toml and fill in your D1 database ID and KV namespace ID.

Apply migrations:

npx wrangler d1 migrations apply telegram-mcp-serverless-db --remote

Set secrets:

npx wrangler secret put MCP_BEARER_TOKEN
npx wrangler secret put TELEGRAM_API_ID
npx wrangler secret put TELEGRAM_API_HASH
npx wrangler secret put TELEGRAM_SESSION

Deploy:

npx wrangler deploy

Telegram session

The Worker expects an exported mtcute string session in TELEGRAM_SESSION. The first successful Telegram call imports it, then session/cache state is persisted into KV and mirrored into D1.

Do not commit the session string. Treat it like a password to your Telegram account.

Testing with curl

Set environment variables locally:

export MCP_URL="https://your-worker.workers.dev"
export MCP_BEARER_TOKEN="your-local-copy-of-the-token"

Run the smoke test:

npm run smoke

Manual checks:

curl -i "$MCP_URL/healthz"

curl -i \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  "$MCP_URL/mcp"

curl -sS \
  -H "Authorization: Bearer $MCP_BEARER_TOKEN" \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  "$MCP_URL/mcp"

The unauthenticated request should return 401. The authenticated request should return the tool list.

Cost and operations

For a private MCP server, this model is often cheaper and simpler than a VPS because there is no always-on app server. Cloudflare provides TLS, deployment, scaling, Cron, Queue consumers, KV, and D1 as managed services.

You still need to watch platform limits: Worker CPU/runtime limits, D1/KV quotas, Queue limits, and Telegram flood limits. For typical personal-agent usage, requests are short and intermittent, which fits Workers well.

Repository layout

src/worker.js                 MCP HTTP endpoint, auth, tool dispatch, D1/KV operations
src/telegram-live.js          Telegram MTProto client setup through mtcute
src/memory-storage.js         mtcute-compatible storage adapter with serializable dump
migrations/0001_schema.sql    dialogs/messages/FTS/tags/contacts/sync_jobs
migrations/0002_*.sql         D1 session mirror and small media/cache table
scripts/smoke-test.sh         curl smoke test
wrangler.example.toml         Cloudflare bindings template

License

MIT