Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y @overpod/[email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
claude mcp add overpod-mcp-telegram -- npx -y @overpod/mcp-telegram@1.45.1In einem Terminal ausführen.
{ "mcpServers": { "overpod-mcp-telegram": { "command": "npx", "args": [ "-y", "@overpod/[email protected]" ] } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Starten📖 Documentation · ☁️ Cloud version — connect Telegram to Claude.ai or ChatGPT in 30 seconds with QR code, no API keys needed. Telegram MCP Server — a Model Context Protocol server that connects AI assistants like Claude and ChatGPT to Telegram via the MTProto protocol. Unlike bots, this runs as a userbot -- it operates under your personal Telegram account using GramJS, giving full access to your chats, contacts, and message history.
{pts, qts, date} stateMCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)API_ID and API_HASH from my.telegram.orgTELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login
A QR code will appear in the terminal. Open Telegram on your phone, go to Settings > Devices > Link Desktop Device, and scan the code. The session is saved to ~/.mcp-telegram/session and reused automatically.
Custom session path: set
TELEGRAM_SESSION_PATH=/path/to/sessionto store the session file elsewhere.
Two-step verification (2FA): if your account has a cloud password enabled, scanning the QR code is not enough — Telegram also requires the password. Provide it via
TELEGRAM_2FA_PASSWORDso the login can complete:TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram loginThe password is only used locally to answer Telegram's SRP challenge and is never persisted.
claude mcp add telegram -s user \
-e TELEGRAM_API_ID=YOUR_ID \
-e TELEGRAM_API_HASH=YOUR_HASH \
-- npx @overpod/mcp-telegram
That's it! Ask Claude to run telegram-status to verify.
Use TELEGRAM_SESSION_PATH to run separate Telegram accounts side by side:
# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login
Then add each as a separate MCP server:
claude mcp add telegram-work -s user \
-e TELEGRAM_API_ID=ID1 \
-e TELEGRAM_API_HASH=HASH1 \
-e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
-- npx @overpod/mcp-telegram
claude mcp add telegram-personal -s user \
-e TELEGRAM_API_ID=ID2 \
-e TELEGRAM_API_HASH=HASH2 \
-e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
-- npx @overpod/mcp-telegram
Each account gets its own session file — no conflicts.
The opposite of multiple accounts: one account driven by many clients at once — several Claude Code windows, parallel sub-agents, or multiple IDEs. Normally each process opens the same session and they evict one another with AUTH_KEY_DUPLICATED. Serve mode fixes this.
Run a single persistent daemon that owns the one Telegram connection. Every other process auto-detects the daemon (via a PID lock) and becomes a thin client that proxies tool calls to it over a local Unix socket:
# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)
Then point each MCP client at the same install with the same TELEGRAM_SESSION_PATH — no serve argument. They connect to the daemon automatically; closing any client never drops the shared connection. Credentials are only required by the daemon (the owner), so client commands can omit TELEGRAM_API_ID/TELEGRAM_API_HASH and keep them where the daemon runs.
See the shared daemon guide for a systemd unit and SSH usage.
If Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:
# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram
# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram
If your VPS or hosting IP is reachable on outbound port 443 but not the default MTProto port 80 (some cloud providers ban port 80 on Telegram DC IP ranges as anti-abuse policy), set:
TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram
No need to clone or install anything. Just use npx @overpod/mcp-telegram.
npm install -g @overpod/mcp-telegram
mcp-telegram # run server
mcp-telegram login # QR login
Download from Releases — standalone single-file binaries, zero dependencies:
# Download (example for 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
# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login
# Run
./mcp-telegram
git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build
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 MCP 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
Note: Login must be done once via terminal. After that, the session is persisted in
~/.mcp-telegramand reused automatically.
claude mcp add telegram -s user \
-e TELEGRAM_API_ID=YOUR_ID \
-e TELEGRAM_API_HASH=YOUR_HASH \
-- npx @overpod/mcp-telegram
Open your config file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonAdd the Telegram server:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["@overpod/mcp-telegram"],
"env": {
"TELEGRAM_API_ID": "YOUR_ID",
"TELEGRAM_API_HASH": "YOUR_HASH"
}
}
}
}
Restart Claude Desktop.
Ask Claude: "Run telegram-login" -- a QR code will appear. If the image is not visible, it's also saved to ~/.mcp-telegram/qr-login.png. Scan it in Telegram (Settings > Devices > Link Desktop Device).
Ask Claude: "Run telegram-status" to verify the connection.
Note: No terminal required! Login works entirely through Claude Desktop.
Same setup, but using the pre-built binary instead of npx:
{
"mcpServers": {
"telegram": {
"command": "/path/to/mcp-telegram",
"env": {
"TELEGRAM_API_ID": "YOUR_ID",
"TELEGRAM_API_HASH": "YOUR_HASH"
}
}
}
}
Login via terminal first (see Docker section above).
Add to your config file:
{
"mcpServers": {
"telegram": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "TELEGRAM_API_ID=YOUR_ID",
"-e", "TELEGRAM_API_HASH=YOUR_HASH",
"-v", "~/.mcp-telegram:/root/.mcp-telegram",
"mcp-telegram"
]
}
}
}
Add the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).
import { MCPClient } from "@mastra/mcp";
const telegramMcp = new MCPClient({
id: "telegram-mcp",
servers: {
telegram: {
command: "npx",
args: ["@overpod/mcp-telegram"],
env: {
TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
},
},
},
});
All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.
Tip: Ask your AI assistant "What Telegram tools are available?" to get the full list with parameters and descriptions.
Some tools are disabled by default and must be opted in via environment variables:
Add these to your .env file or MCP client config to enable them.
npm run dev # Start with file watching (tsx)
npm start # Start the MCP server
npm run login # QR code login in terminal
npm run build # Compile TypeScript
npm run lint # Check code with Biome
npm run lint:fix # Auto-fix lint issues
npm run format # Format code with Biome
src/
index.ts -- MCP server entry point
telegram-client.ts -- TelegramService class (GramJS wrapper)
qr-login-cli.ts -- CLI utility for QR code login
tools/ -- Modular tool definitions
auth.ts -- Connection & login
messages.ts -- Send, read, search, edit, delete, forward; inline bots; real-time polling
chats.ts -- Chat listing, group management, admin toggles, stats
contacts.ts -- Contacts, profiles, moderation
media.ts -- Files, photos, downloads
reactions.ts -- Reactions, set-chat-reactions
extras.ts -- Pin, schedule, polls, topics
stickers.ts -- Sticker sets, send, search, browse
account.ts -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
business.ts -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
boosts.ts -- Boost status, my boosts, boosters list
stories.ts -- Stories: list all, peer, by-id, view stats
group-calls.ts -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
stars.ts -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
quick-replies.ts -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
shared.ts -- Shared utilities
telegram) -- Telegram MTProto clientA Telegram session can only be used by one process at a time. If you get AUTH_KEY_DUPLICATED, it means another process is already using the same session file.
Solution: Create separate sessions for each environment:
# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login
# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login
Then set TELEGRAM_SESSION_PATH in each environment's MCP config accordingly.
.env (gitignored)~/.mcp-telegram/session with 0600 permissions (owner-only access)0700 permissionsAUTH_KEY_DUPLICATED errors (see Troubleshooting)MIT
MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.
{ "mcpServers": { "overpod-mcp-telegram": { "command": "npx", "args": [ "-y", "@overpod/[email protected]" ] } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
@overpod/mcp Telegram läuft lokal über stdio.
Zuletzt geprüft: 2026-11-15. MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.
