Skip to main content
Glama
enesjakozh
sparfenyuk

Telegram MCP Server

by sparfenyuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

텔레그램 MCP 서버

에 대한

이 서버는 Telegram API와 AI 어시스턴트를 연결하는 다리 역할을 하며 Model Context Protocol을 기반으로 합니다.

[!중요] 이 서버를 사용하기 전에 Telegram API 서비스 약관을 읽고 이해했는지 확인하십시오. Telegram API를 오용할 경우 계정이 정지될 수 있습니다.

Related MCP server: telegram-briefing-mcp

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Claude Desktop과 같은 AI 앱이 외부 도구 및 데이터 소스에 연결할 수 있도록 하는 시스템입니다. AI 어시스턴트가 사용자의 제어권을 유지하면서 로컬 서비스 및 API를 사용할 수 있는 명확하고 안전한 방법을 제공합니다.

이 서버는 무슨 역할을 하나요?

현재 해당 서버는 Telegram API에 대한 읽기 전용 액세스를 제공합니다.

  • [x] 대화 목록(채팅, 채널, 그룹) 가져오기

  • [x] 주어진 대화 상자에서 (읽지 않은) 메시지 목록을 가져옵니다.

  • [ ] 채널을 읽음으로 표시

  • [ ] 날짜 및 시간별로 메시지 검색

  • [ ] 미디어 파일 다운로드

  • [ ] 연락처 목록을 가져옵니다

  • [ ] 메시지 초안 작성

  • ...

실제 사용 사례

  • [x] 읽지 않은 메시지 요약을 만듭니다.

  • [ ] 다가오는 생일을 가진 연락처를 찾아 인사말을 예약하세요

  • [ ] 주어진 주제에 대한 토론을 찾아 요약하고 링크 목록을 제공합니다.

필수 조건

설치

지엑스피1

[!NOTE] 이미 서버를 설치한 경우 uv tool upgrade --reinstall 명령을 사용하여 업데이트할 수 있습니다.

[!NOTE] 서버를 삭제하려면 uv tool uninstall mcp-telegram 명령을 사용하세요.

구성

Telegram API 구성

서버를 사용하려면 먼저 Telegram API에 연결해야 합니다.

  1. Telegram API 에서 API ID와 해시를 가져옵니다.

  2. 다음 명령을 실행하세요.

    mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>

    Telegram에서 받은 코드를 입력하여 API에 연결하세요.

    2단계 인증이 활성화된 경우 비밀번호가 필요할 수 있습니다.

[!NOTE] Telegram API에서 로그아웃하려면 mcp-telegram logout 명령을 사용하세요.

클로드 데스크톱 구성

Claude Desktop이 Exa MCP 서버를 인식하도록 구성합니다.

  1. Claude Desktop 구성 파일을 엽니다.

    • MacOS에서는 구성 파일이 ~/Library/Application Support/Claude/claude_desktop_config.json 에 있습니다.

    • Windows에서 구성 파일은 %APPDATA%\Claude\claude_desktop_config.json 에 있습니다.

    참고: Claude Desktop 앱 설정 내부에서도 claude_desktop_config.json을 찾을 수 있습니다.

  2. 서버 구성 추가

    {
  "mcpServers": {
    "mcp-telegram": {
        "command": "mcp-server",
        "env": {
          "TELEGRAM_API_ID": "<your-api-id>",
          "TELEGRAM_API_HASH": "<your-api-hash>",
        },
      }
    }
  }
}

텔레그램 구성

Telegram API를 사용하기 전에 고유한 API ID와 해시를 얻어야 합니다.

  1. 사용할 개발자 계정의 전화번호로 Telegram 계정에 로그인하세요.

  2. API 개발 도구를 클릭하세요.

  3. '새 애플리케이션 만들기' 창이 나타납니다. 애플리케이션 세부 정보를 입력하세요. URL은 입력할 필요가 없으며, 처음 두 필드(앱 제목과 짧은 이름)만 나중에 변경할 수 있습니다.

  4. 마지막에 있는 '애플리케이션 만들기'를 클릭하세요. API 해시는 비밀로 유지되며 Telegram에서는 해시를 취소할 수 없습니다. 어디에도 게시하지 마세요!

개발

시작하기

  1. 저장소를 복제합니다

  2. 종속성을 설치하세요

    uv sync

  3. 서버를 실행하세요

    uv run mcp-telegram --help

src/mcp_telegram/tools.py 파일에 도구를 추가할 수 있습니다.

새로운 도구를 추가하는 방법:

  1. ToolArgs에서 상속되는 새 클래스를 만듭니다.

    class NewTool(ToolArgs):
    """Description of the new tool."""
    pass

    클래스의 속성은 도구의 인수로 사용됩니다. 클래스 docstring은 도구 설명으로 사용됩니다.

  2. 새 클래스에 대한 tool_runner 함수를 구현합니다.

    @tool_runner.register
async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]:
    pass

    이 함수는 TextContent, ImageContent 또는 EmbeddedResource의 시퀀스를 반환해야 합니다. 이 함수는 비동기적이어야 하며 새 클래스의 단일 인수를 받아야 합니다.

  3. 완료! 클라이언트를 다시 시작하면 새 도구를 사용할 수 있습니다.

검증은 Claude Desktop을 통해서나 도구를 직접 실행하여 수행할 수 있습니다.

터미널에서 서버 디버깅

도구를 직접 실행하려면 다음 명령을 사용하세요.


# List all available tools
uv run cli.py list-tools

# Run the concrete tool
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

Inspector에서 서버 디버깅

MCP 검사기는 멋진 UI를 사용하여 서버 디버깅을 지원하는 도구입니다. 실행하려면 다음 명령을 사용하세요.

npx @modelcontextprotocol/inspector uv run mcp-telegram

[!WARNING] 검사기에서 환경 변수 TELEGRAM_API_ID 및 TELEGRAM_API_HASH를 정의하는 것을 잊지 마세요.

문제 해결

'MCP 서버 mcp-telegram에 연결할 수 없습니다' 메시지

Claude Desktop에서 'MCP 서버 mcp-telegram에 연결할 수 없습니다'라는 메시지가 나타나면 서버 구성이 잘못되었다는 의미입니다.

다음을 시도해 보세요.

  • 구성 파일에서 uv 바이너리의 전체 경로를 사용하세요.

  • 구성 파일에서 복제된 저장소 경로를 확인하세요

Available Tools

2 tools
ListDialogsC

List available dialogs, chats and channels.

ParametersJSON Schema
NameRequiredDescriptionDefault
unreadNo
archivedNo
ignore_pinnedNo

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool does (listing) without mentioning permissions, rate limits, pagination, or response format. For a list tool with zero annotation coverage, this leaves critical behavioral traits unspecified, making it inadequate for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly. However, it lacks depth, which affects completeness but not conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a list operation with 3 parameters), no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what 'available' means, how results are returned, or parameter usage, leaving significant gaps for the agent to operate effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description repeats the tool name and provides no information about parameters. With 3 parameters (unread, archived, ignore_pinned) and 0% schema description coverage, the schema only provides titles and types without explanations. The description fails to compensate by adding any meaning or context for these parameters, leaving them undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool's purpose as listing available dialogs, chats, and channels, which is clear but vague. It uses the verb 'list' with the resources 'dialogs, chats and channels', but doesn't specify scope (e.g., all or filtered) or distinguish it from the sibling tool ListMessages. This makes it adequate but with gaps in specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool ListMessages, prerequisites, or exclusions. Without any usage context, the agent must infer when this tool is appropriate, which is insufficient for effective tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ListMessagesA
List messages in a given dialog, chat or channel. The messages are listed in order from newest to oldest.

If `unread` is set to `True`, only unread messages will be listed. Once a message is read, it will not be
listed again.

If `limit` is set, only the last `limit` messages will be listed. If `unread` is set, the limit will be
the minimum between the unread messages and the limit.
ParametersJSON Schema
NameRequiredDescriptionDefault
dialog_idYes
unreadNo
limitNo

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the ordering (newest to oldest), the effect of 'unread' (filters to unread only and excludes read messages), and how 'limit' interacts with 'unread' (minimum between them). However, it misses details like pagination, error handling, or authentication needs, leaving gaps for a mutation-like operation (listing can imply read access).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose. Each sentence adds value: the first states the action, the second explains ordering, and the subsequent ones detail parameter effects without redundancy. There's zero waste, making it efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and 3 parameters with 0% schema coverage, the description provides a decent foundation by explaining purpose and parameter interactions. However, it lacks information on return values (e.g., message format), error cases, or authentication requirements, making it incomplete for full contextual understanding in a read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds significant meaning beyond the schema by explaining the semantics of 'unread' (filters to unread messages and excludes read ones) and 'limit' (applies to last messages, with interaction rules when combined with 'unread'). This covers key aspects of the 3 parameters, though it doesn't detail 'dialog_id' beyond context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('messages in a given dialog, chat or channel'), making the purpose immediately understandable. It distinguishes from the sibling tool 'ListDialogs' by specifying messages rather than dialogs. However, it doesn't explicitly contrast with potential alternatives beyond the sibling tool, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining the effects of the 'unread' and 'limit' parameters, which suggests when to use them. However, it lacks explicit guidance on when to choose this tool over alternatives (e.g., vs. a search tool or the sibling 'ListDialogs'), and doesn't mention prerequisites like required permissions or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedListDialogs
    • First observedListMessages
Deploy Server
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

TDQS

C2.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: ListDialogs retrieves available dialogs/chats/channels, while ListMessages retrieves messages within a specific dialog/chat/channel. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with PascalCase naming (ListDialogs, ListMessages). The naming is predictable and readable throughout the set.

Tool Count2/5

With only 2 tools, this server feels severely under-scoped for a Telegram integration. While the tools are well-defined, there are obvious gaps in functionality (e.g., sending messages, managing channels, handling media) that limit its usefulness.

Completeness2/5

The tool surface is significantly incomplete for a Telegram server. It only provides read-only listing capabilities for dialogs and messages, missing essential operations like sending messages, creating/editing channels, handling files, or any write/update actions that would be expected in a messaging platform integration.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • telegram-briefing-mcp

    zainbacchus
    A
    license
    Not graded
    quality
    D
    maintenance
    A read-only Telegram MCP server that retrieves messages from your DMs, groups, and channels, enabling Claude to generate executive briefings from Telegram conversations.
    MIT

  • telegram-mcp

    Sultonbek006
    A
    license
    Not graded
    quality
    D
    maintenance
    A Telegram integration for Claude, Cursor, and other MCP-compatible clients, exposing account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using Telethon.
    Apache 2.0

  • Telegram MCP Server

    Asadullayev06
    A
    license
    Not graded
    quality
    B
    maintenance
    A Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using Telethon.
    Apache 2.0

Appeared in Searches