Installation

Pre-Built Binary (Recommended)

Download a standalone binary — no Node.js, no npm, no dependencies. Just one file.

Download from GitHub Releases:

Platform	Server	Login
macOS ARM64 (Apple Silicon)	mcp-telegram-darwin-arm64	mcp-telegram-login-darwin-arm64
macOS x64 (Intel)	mcp-telegram-darwin-x64	mcp-telegram-login-darwin-x64
Linux x64	mcp-telegram-linux-x64	mcp-telegram-login-linux-x64
Linux ARM64	mcp-telegram-linux-arm64	mcp-telegram-login-linux-arm64
Windows x64	mcp-telegram-windows-x64.exe	mcp-telegram-login-windows-x64.exe

macOS (Apple Silicon)

curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-darwin-arm64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-darwin-arm64
chmod +x mcp-telegram mcp-telegram-login

macOS (Intel)

curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-darwin-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-darwin-x64
chmod +x mcp-telegram mcp-telegram-login

Linux x64

curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

Linux ARM64

curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-arm64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-arm64
chmod +x mcp-telegram mcp-telegram-login

Windows

# Download from GitHub Releases:
# https://github.com/mcp-telegram/mcp-telegram/releases/latest
# Files: mcp-telegram-windows-x64.exe, mcp-telegram-login-windows-x64.exe

Why binary?

• No runtime to install or manage
• No version conflicts
• Copy one file, run it — that's it
• Same features as the npm version

npx (Alternative)

If you already have Node.js 18+, you can use npx — no install needed:

npx @overpod/mcp-telegram login   # login
npx @overpod/mcp-telegram         # run server

npm Global Install

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

Docker

Build the image:

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

Login (interactive terminal required):

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

Run the server:

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

TIP

Login must be done once via terminal. After that, the session is persisted in ~/.mcp-telegram and reused automatically.

From Source

git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build

Proxy Support

If Telegram is blocked in your region or you're running in a containerized environment:

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
./mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee0000...0000 \
./mcp-telegram

Variable	Description
TELEGRAM_PROXY_IP	Proxy server address
TELEGRAM_PROXY_PORT	Proxy server port
TELEGRAM_PROXY_SOCKS_TYPE	4 or 5 (default: 5)
TELEGRAM_PROXY_SECRET	MTProxy secret (enables MTProxy mode)
TELEGRAM_PROXY_USERNAME	Optional proxy auth
TELEGRAM_PROXY_PASSWORD	Optional proxy auth

WSS Transport (Port 443)

Some VPS/hosting IP ranges (e.g. certain Hostinger, OVH and similar shared-VPS providers) block outbound port 80 to Telegram DC IP blocks as anti-abuse policy, while the same DCs stay reachable on port 443. The default MTProto TCPFull transport connects on port 80, so on these hosts the client hangs forever in Connecting to ...:80/TCPFull....

Set TELEGRAM_USE_WSS=true to switch the transport to port 443:

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

Variable	Description
TELEGRAM_USE_WSS	When true, gramJS uses port 443 instead of 80 for the MTProto TCPFull transport. Default: false. Cannot be combined with TELEGRAM_PROXY_* (gramJS limitation) — if both are set, useWSS is ignored and the proxy takes precedence (a warning is logged).

Next Step

→ Login with QR Code