mctl-telegram MCP

Remote MCP server exposing your Telegram user-account (read dialogs, read unread, send draft) to Claude.ai and other MCP clients.

MCP endpoint
https://tg.mctl.ai/mcp
Streamable HTTP — works via POST with Accept: application/json, text/event-stream. Opening it in a browser is expected to be blank.

1. Add as a custom connector in Claude.ai

Open claude.ai → Settings → Connectors and click Add custom connector.
Paste the Remote MCP URL: https://tg.mctl.ai/mcp
Authentication: OAuth. Claude.ai discovers the authorization server from the well-known document at https://tg.mctl.ai/.well-known/oauth-protected-resource and redirects to https://api.mctl.ai for GitHub login.
Sign in with the GitHub account that has access to your mctl tenant. The issued JWT is verified by mctl-telegram via shared HMAC.

2. Available tools

Tool	Annotation	Notes
`list_dialogs`	readOnly	Inputs: `limit` (≤200, default 50), optional `query`.
`get_unread_messages`	readOnly	Inputs: optional `peer`, `limit` (≤200).
`send_message`	destructive	Default `mode=draft` returns a dry-run preview. Real send requires server `ALLOW_SEND=true` + scope `telegram:messages:send` + per-account `send_enabled=true` + `mode=send`.

3. Smoke-test from your terminal

Confirm the well-known and a JSON-RPC handshake before adding the connector:

curl -s https://tg.mctl.ai/.well-known/oauth-protected-resource

curl -s -X POST https://tg.mctl.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'

4. First-time Telegram login

Until the in-browser /telegram/connect flow ships, the operator runs the CLI binary mctl-telegram-login bundled in the same image. It performs phone → SMS code → optional 2FA password and persists an AES-256-GCM-encrypted MTProto session keyed to your GitHub login. The full recipe lives in the repo README.

Source: github.com/mctlhq/mctl-telegram · Auth server: https://api.mctl.ai · Resource: https://tg.mctl.ai