Skip to main content
Glama
enesjakozh
sparfenyuk

Telegram MCP Server

by sparfenyuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Telegram MCP サーバー

について

サーバーは、Telegram API と AI アシスタント間のブリッジであり、モデルコンテキストプロトコルに基づいています。

[!重要] このサーバーをご利用になる前に、 Telegram APIの利用規約を必ずお読みください。Telegram APIを不正に使用した場合、アカウントが停止される可能性があります。

Related MCP server: telegram-briefing-mcp

MCPとは何ですか?

モデルコンテキストプロトコル（MCP）は、Claude DesktopのようなAIアプリが外部ツールやデータソースに接続できるようにするシステムです。これにより、AIアシスタントがユーザーの制御を維持しながら、ローカルサービスやAPIを明確かつ安全に操作できるようになります。

このサーバーは何をしますか?

現時点では、サーバーは Telegram API への読み取り専用アクセスを提供します。

  • [x] ダイアログ（チャット、チャンネル、グループ）のリストを取得します

  • [x] 指定されたダイアログ内の（未読）メッセージのリストを取得します

  • [ ] チャンネルを既読にする

  • [ ] 日付と時刻でメッセージを取得する

  • [ ] メディアファイルをダウンロードする

  • [ ] 連絡先リストを取得する

  • [ ] メッセージの下書き

  • ...

実用的なユースケース

  • [x] 未読メッセージの要約を作成する

  • [ ] 誕生日が近い連絡先を検索し、挨拶の予定を立てる

  • [ ] 特定のトピックに関する議論を検索し、要約し、リンクのリストを提供する

前提条件

インストール

uv tool install git+https://github.com/sparfenyuk/mcp-telegram

[!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>

    API に接続するには、Telegram から受け取ったコードを入力します。

    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_config.json は Claude Desktop アプリの設定内にもあります。

  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を入力する必要はありません。また、最初の2つのフィールド（アプリケーションタイトルと短縮名）のみ、現在後から変更できます。

  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}'

インスペクターでサーバーをデバッグする

MCPインスペクターは、洗練されたUIを使用してサーバーのデバッグを支援するツールです。実行するには、次のコマンドを使用します。

npx @modelcontextprotocol/inspector uv run mcp-telegram

[!警告] インスペクターで環境変数 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