Skip to main content
Glama
Sign In
deenesjakoruzh
telegram-mcp

telegram-mcp

by Shaan-alpha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Telegram MCP Server

로컬 Model Context Protocol 서버로, AI 에이전트(Claude Code, Claude Desktop 또는 모든 MCP 클라이언트)가 여러분의 Telegram 계정에 통제된 방식으로 접근할 수 있게 해줍니다: 채팅 목록 보기, 기록 읽기, 검색, 메시지 보내기 등을 Telegram의 MTProto API를 통해 수행합니다.

Python + Telethon로 구축되었습니다. 전적으로 여러분의 머신에서 실행되며, 로그인 세션은 절대 외부로 나가지 않습니다.

Python MCP License

왜 필요한가

Telegram의 Bot API는 기존 채팅을 볼 수 없습니다; 봇은 별도의 정체성을 가지며 명시적으로 보낸 메시지만 수신합니다. 에이전트가 여러분의 실제 대화를 다루게 하려면 MTProto 클라이언트 API가 필요하며, 사용자 계정으로 인증해야 합니다. 이 프로젝트는 이를 작고 집중된 MCP 서버로 감싸서, MCP를 지원하는 모든 에이전트가 여러분의 Telegram을 읽고 조작할 수 있게 합니다. 매번 접착 코드를 작성할 필요 없이 말이죠.

Related MCP server: tdlib-mcp-server

구성 방식

Telegram 봇은 별도의 정체성을 가지며 자신에게 보내진 메시지만 볼 수 있습니다. 에이전트가 여러분의 대화를 다루게 하려면 서버가 MTProto를 통해 사용자 계정으로 인증해야 하며, 그래서 세션 문자열이 그만큼 중요합니다.

flowchart LR
    AGENT["<b>MCP client</b><br/>Claude Code · Claude Desktop<br/>or any MCP-capable agent"]

    subgraph LOCAL ["Your machine — nothing leaves it but Telegram traffic"]
        direction TB
        SRV["<b>server.py</b> · FastMCP stdio server<br/>connects lazily on first tool call<br/>verifies the session is authorized"]
        TOOLS["<b>6 tools</b><br/>get_me · list_chats · get_history<br/>search_messages · search_all · send_message"]
        ENV[("<b>.env</b> · git-ignored<br/>api_id · api_hash<br/><b>SESSION_STRING</b><br/><i>equivalent to being logged in as you</i>")]
        LOGIN["<b>login.py</b> · run once<br/>phone + code + 2FA → StringSession"]
        SRV --> TOOLS
        LOGIN -->|"writes"| ENV
        ENV -->|"reads"| SRV
    end

    subgraph TL ["Telethon → MTProto"]
        direction TB
        M1["iter_dialogs"]
        M2["iter_messages"]
        M3["SearchGlobalRequest"]
        M4["send_message"]
    end

    TG[("<b>Telegram</b><br/>your real account,<br/>your existing chats")]
    BOT(["Bot API<br/><i>cannot see your chats —<br/>this is why MTProto</i>"])

    AGENT <-->|"MCP over stdio"| SRV
    TOOLS --> M1
    TOOLS --> M2
    TOOLS --> M3
    TOOLS --> M4
    TL <--> TG
    BOT -.->|"✗"| TG

    classDef secret fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fee2e2
    classDef no fill:#0f172a,stroke:#475569,stroke-width:1.5px,color:#94a3b8
    classDef core fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e2e8f0
    class ENV secret
    class BOT no
    class SRV,TOOLS core

결과는 일반 JSON 직렬화 가능한 dict로 반환되므로, 에이전트는 스크랩된 텍스트가 아닌 구조화된 데이터를 요약합니다.

기능

  • 6가지 도구 — 일반적인 읽기/쓰기 작업을 다룹니다 (아래 참조)

  • 로컬 전용 — 자격 증명과 세션은 git-ignore된 .env에 저장되며, Telegram 외에는 아무데도 전송되지 않습니다

  • 표준 MCP stdio 서버 — Claude Code, Claude Desktop 또는 모든 MCP 클라이언트와 호환됩니다

  • 일회성 로그인 — 대화형 스크립트가 재사용 가능한 세션 문자열을 저장합니다; 매 실행마다 재인증할 필요가 없습니다

  • 작고 읽기 쉬움 — Python 약 150줄, 감사와 확장이 쉽습니다

도구

도구

설명

get_me()

연결된 계정 반환 (정상 확인)

list_chats(limit=20)

가장 최근 대화 목록

get_history(chat, limit=30)

한 채팅의 최근 메시지

search_messages(chat, query, limit=30)

한 채팅 내 검색

search_all(query, limit=30)

모든 채팅을 한 번에 검색

send_message(chat, text)

여러분으로서 메시지 보내기

chat은 사용자 이름(@name), 숫자 ID, 전화번호, t.me 링크 또는 채팅의 표시 이름을 허용합니다.

빠른 시작

1. 설치

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. API 자격 증명 얻기

my.telegram.org → API development tools → 앱 생성 → api_id와 api_hash를 복사하세요.

3. 로그인 (일회성)

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

api_id/api_hash, 전화번호(국가 코드 포함), Telegram이 보낸 로그인 코드(2FA 비밀번호가 설정된 경우 포함)를 입력하세요. 이 과정은 재사용 가능한 세션을 .env에 기록합니다.

4. MCP 클라이언트에 등록

Claude Code:

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop — claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

클라이언트를 다시 시작하면 telegram 도구를 사용할 수 있습니다.

예시

당신: 모든 Telegram 채팅에서 "invoice"를 검색하고 미결제 항목을 요약해 줘.

에이전트가 search_all("invoice")를 호출하면 다음이 반환됩니다:

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

…그리고 에이전트는 그 결과를 바탕으로 요약합니다.

작동 방식

login.py는 Telethon을 통해 한 번 인증하고 StringSession을 .env에 저장합니다. server.py는 FastMCP stdio 서버를 구축하고, 첫 도구 호출 시 지연 연결하며, 세션이 인증되었는지 확인하고, 각 도구를 Telethon 호출(iter_dialogs, iter_messages, SearchGlobalRequest, send_message)에 매핑합니다. 결과는 일반 JSON 직렬화 가능한 dict로 반환됩니다.

보안

  • .env를 비공개로 유지하세요. SESSION_STRING은 여러분으로 로그인된 것과 동일합니다. git-ignore되어 있으므로 절대 커밋하지 마세요.

  • 모든 것이 로컬에서 실행됩니다; 서버는 Telegram 서버와만 통신합니다.

  • 사용자 계정을 자동화하는 것은 Telegram 서비스 약관의 회색 지대입니다. 자신의 계정을 읽는 것은 일반적으로 괜찮습니다; 보내는 속도를 사람 수준으로 유지하고 대량/스팸 활동을 피해 계정 제한을 피하세요.

제한 사항

  • 아직 자동화된 테스트 스위트가 없습니다; 실제 계정으로 수동 검증했습니다.

  • search_messages는 단일 채팅을 검색합니다; 전체 검색은 search_all을 사용하세요.

  • 표시 이름 확인은 대화 목록을 스캔하는 방식으로 대체되므로, 정확한 사용자 이름/ID가 더 빠르고 안정적입니다.

라이선스

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

ActivityStale
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • telegram-mcp

    VovaVindar
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to read, send, and organize Telegram messages and chats. Supports tools for listing chats, fetching messages, sending/reply, archiving, muting, and folder management.
    1
    MIT

  • 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

    naim30
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to control a real Telegram user account via MTProto, allowing message sending, chat reading/searching, and message management through MCP tools.
    30 npm
    -

  • Telegram MCP Server

    Muhammadyunusxon
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to control a personal Telegram account for sending/reading messages, media, group management, and more via the MTProto API.
    MIT

Appeared in Searches