Skip to main content
Glama
deenesjakoruzh
Steph-ux

telegram-mcp-server

by Steph-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-mcp-server

Ein Telegram-MCP-Server auf Basis von Telethon — persistenter Client, flood-sicher, 9 gruppierte Tools.

Null API-Schlüssel im Code. Sitzungsdateien werden lokal gespeichert. Funktioniert mit Benutzerkonten (2FA) und Bots.

1. Installation

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

API-Anmeldedaten abrufen

  1. Gehe zu my.telegram.org

  2. Melde dich mit deiner Telefonnummer an

  3. Erstelle eine App → erhalte API ID und API Hash

Einmalige Authentifizierung

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

Related MCP server: telegram-mcp

2. In deinem MCP-Client registrieren

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Falls nicht im PATH:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

3. Tool-Katalog (9 Tools, 8 Aktionen)

tg_session — Sitzungsverwaltung

Aktion

Erforderliche Argumente

Beschreibung

auth

api_id, api_hash, phone oder bot_token

Authentifizieren (2FA unterstützt)

check

—

Anmeldestatus prüfen

logout

—

Sitzung löschen

tg_message — Senden, weiterleiten, löschen, antworten

Aktion

Erforderliche Argumente

Beschreibung

send

target, text

Eine Nachricht senden

forward

target, message_id, to_target

Eine Nachricht weiterleiten

delete

target, message_id

Eine Nachricht löschen

reply

target, message_id, text

Auf eine Nachricht antworten

tg_chat — Chat-Operationen

Aktion

Erforderliche Argumente

Beschreibung

list

—

Letzte Chats auflisten

info

target

Chat-Informationen abrufen

members

target

Chat-Mitglieder auflisten

leave

target

Einen Chat verlassen

tg_search — Suche

Aktion

Erforderliche Argumente

Beschreibung

messages

query

Nachrichten suchen (optional in target)

users

query

Kontakte/Benutzer suchen

channels

query

Kanäle suchen

tg_history — Chat-Verlauf

Aktion

Erforderliche Argumente

Beschreibung

messages

target

Nachrichtenverlauf abrufen

media

target

Nur Medien-Verlauf abrufen

files

target

Nur Dateien-Verlauf abrufen

tg_user — Benutzer-Operationen

Aktion

Erforderliche Argumente

Beschreibung

me

—

Eigene Informationen abrufen

info

target

Benutzerinformationen abrufen

block

target

Einen Benutzer blockieren

unblock

target

Einen Benutzer entsperren

tg_media — Medien senden

Aktion

Erforderliche Argumente

Beschreibung

send_photo

target, file_path

Ein Foto senden

send_video

target, file_path

Ein Video senden

send_file

target, file_path

Ein Dokument senden

send_voice

target, file_path

Eine Sprachnachricht senden

tg_channel — Kanalverwaltung

Aktion

Erforderliche Argumente

Beschreibung

create

title

Eine Supergruppe/einen Kanal erstellen

join

target

Einem Kanal beitreten

leave

target

Einen Kanal verlassen

info

target

Kanalinformationen abrufen

tg_draft — Entwurfsnachrichten

Aktion

Erforderliche Argumente

Beschreibung

save

target, text

Einen Entwurf speichern

list

—

Alle Entwürfe auflisten

delete

target

Einen Entwurf löschen

4. Umgebungsvariablen

Variable

Standard

Beschreibung

TG_API_ID

0

Telegram-API-ID (von my.telegram.org)

TG_API_HASH

""

Telegram-API-Hash

TG_SESSION_DIR

~/.telegram-mcp/sessions

Speicherort der Sitzungsdateien

5. Sicherheit

  • Ratenbegrenzer: Sendeaktionen auf 5/Min. begrenzt. Leseaktionen unbegrenzt.

  • Automatische Wiederholung bei FloodWaitError: Wartet die erforderliche Zeit (begrenzt auf 5 Min.).

  • Sitzungsdateien: Nur lokal, niemals in git committet.

  • 2FA-Unterstützung: Volle Unterstützung für Konten mit Zwei-Faktor-Authentifizierung.

6. MCP-Ressourcen

  • tg://version — Serverversion

  • tg://session/status — Anmeldestatus

Lizenz

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • tdlib-mcp-server

    Crocodile-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
    -

  • telegram-mcp

    chenzhaoxuan0
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
    MIT

  • telegram-mcp

    Shaan-alpha
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
    1
    MIT