AI导哈

Telegram访问代理服务

Telegram MCP服务器，用于从Claude Code访问个人Telegram账户，支持自动化操作和媒体代理功能。

  • by z0rgoyok
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 z0rgoyok/telegram-mcp

使用说明

主要目标：

  • 用于自动化的安全电报访问
  • 媒体代理，使代理可以看到图像

电报mcp

Telegram MCP服务器，用于从Claude Code访问您的个人Telegram帐户。

v2亮点

  • JSON是每个工具的首选合约。
  • 基于光标的聊天/消息/搜索/线程分页。
  • 用于快速LLM基础的上下文和线程工具。
  • 可预测的错误代码：
    • VALIDATION_ERROR
    • NOT_FOUND
    • UNAUTHORIZED
    • RATE_LIMITED
    • PROVIDER_ERROR

响应合同

所有MCP工具返回：

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "cursor": null,
    "has_more": false,
    "request_id": "..."
  }
}

重要 stdio 模式：使用 --service-ports 为了 mcp.没有公布的端口 8902, get_message_media 代理URL将无法访问。

默认情况下，此项目中已发布的Docker端口绑定到 127.0.0.1 只有。

对于工具错误：

{
  "ok": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "from_date is required",
    "details": {
      "field": "from_date"
    }
  },
  "meta": {
    "cursor": null,
    "has_more": false,
    "request_id": "..."
  }
}

刀具目录

  • resolve_chat：通过查询解决聊天候选人(@username、id、title），带有可选的Telegram对话框过滤器(dialog_filter 按姓名或id）。
  • list_chats：列出带有过滤器的对话框、电报文件夹选择、电报对话框过滤器选择、搜索、仅未读和光标分页。
  • list_unread_chats：确定性未读分流(unread_count，activity），并可选择Telegram文件夹。
  • list_dialog_filters：列出可用的Telegram对话框过滤器 id、头衔和同行人数。
  • unsubscribe_from_channel：取消订阅广播频道 chat_id 或 @username.
  • leave_chat：通过以下方式离开群聊或超级群聊 chat_id.
  • list_my_sent_chats：聚合您在所需时间范围内发送消息的聊天记录。
  • list_mentions_to_me_chats：聚合消息中提到您的句柄的聊天。
  • get_messages：使用日期范围、搜索、顺序、光标读取聊天记录。
  • get_message_context：读取目标消息及其前后消息。
  • get_thread_messages：读取根邮件的回复。
  • search_messages：全局/每次聊天搜索；空查询用作通配符。
  • search_mentions_to_me：搜索提及您的句柄的消息(@username)通过聊天。
  • list_replies_to_me：查找回复您消息的消息（全局或每次聊天）。
  • get_messages_batch：在一次通话中阅读多个聊天记录(chat_ids, limit_per_chat).
  • list_media_messages：查找媒体消息（可选 media_kind)全球或每次聊天。
  • list_chat_activity_summary：每个聊天活动的组合：我的消息、提及次数、未读次数。
  • get_chat_snapshot：快速聊天快照(recent_messages，可选 pinned_messages).
  • get_message_media：返回消息附件URL（电报URL或签名的HTTP代理）。
  • export_chat：将整个聊天导出到内存中的JSON文件中，并返回一个签名的下载URL，可以选择使用媒体URL进行丰富。
  • get_auth_status：只读Telegram身份验证状态。
  • health_check：服务/提供商健康诊断。

每个工具都接受 format="json" （默认）或 format="markdown".

聊天发现指南

当客户需要快速且可预测地找到聊天时，请使用以下规则：

  • 使用 resolve_chat(query=...) 当你需要一块混凝土时 chat_id 对于以后的通话，如 get_messages.
  • 使用 list_chats(...) 当你想浏览一个范围并检查几个匹配的聊天记录时。
  • 使用 dialog_filter 用于在Telegram客户端中创建的自定义Telegram选项卡/过滤器。 示例： Fix Price, Unread, Работа.
  • 使用 folder=0 仅适用于存档之外的对话 folder=1 仅用于存档。 folder 并不意味着自定义电报选项卡/过滤器。
  • 请勿合并 folder 和 dialog_filter 在一个请求中。

推荐示例：

  • 发现可用的Telegram过滤器： list_dialog_filters()
  • 最近按标题正常聊天： resolve_chat(query="Engineering")
  • 存在于自定义Telegram过滤器中的聊天： resolve_chat(query="Android Group", dialog_filter="Fix Price")
  • 在自定义筛选器中浏览聊天记录： list_chats(dialog_filter="Fix Price", query="Android")
  • 浏览存档对话框： list_chats(folder=1, query="Support")

性能说明：

  • resolve_chat(query=...) 没有 dialog_filter 可以扫描大型帐户中的许多对话框和过滤器。
  • 如果您知道自定义Telegram筛选器名称，请始终通过 dialog_filter 以减少延迟。

时间过滤器支持：

  • get_messages
  • search_messages
  • list_my_sent_chats
  • list_mentions_to_me_chats
  • search_mentions_to_me
  • list_replies_to_me
  • get_messages_batch
  • list_media_messages
  • list_chat_activity_summary

规则 from_date / to_date:

  • 必须是带时间的ISO8601日期时间，例如 2026-02-15T00:00:00Z.
  • 仅日期值，如 2026-02-15 被拒绝 VALIDATION_ERROR.
  • 对于 list_my_sent_chats, from_date 是必需的。
  • 对于 list_chat_activity_summary, from_date 是必需的。

设置

1.获取Telegram API证书

首选https://my.telegram.org/apps，创建应用程序，注意 api_id 和 api_hash.

2.配置

cd ~/dev/tools/telegram-mcp
cp .env.example .env
# Fill API_ID, API_HASH, PHONE

可选环境：

  • MCP_TRANSPORT （默认值 stdio)-运行时传输(stdio, sse, streamable-http)for python -m telegram_mcp.
  • MCP_HTTP_HOST （默认值 127.0.0.1)-绑定主机 sse/streamable-http 运输。
  • MCP_HTTP_PORT （默认值 8000)-绑定端口 sse/streamable-http 运输。
  • MCP_MOUNT_PATH （默认值 /)-可选的SSE挂载前缀。
  • DIALOG_SCAN_LIMIT （默认值 1000)-对话框扫描操作的上限。
  • MEDIA_DOWNLOAD_LIMIT_BYTES （默认值 8388608)-媒体代理下载的最大附件大小。
  • MEDIA_PROXY_HOST （默认值 0.0.0.0)-为内部媒体代理绑定主机。
  • MEDIA_PROXY_PORT （默认值 8902)-绑定内部媒体代理的端口。
  • MEDIA_PROXY_PUBLIC_BASE_URL （默认值 http://localhost:8902)-返回给MCP客户端的基本URL。
  • MEDIA_PROXY_TOKEN_SECRET （默认值 API_HASH)-签名媒体URL的HMAC密钥。
  • MEDIA_PROXY_TOKEN_TTL_SECONDS （默认值 3600)-已签名的媒体URL生存期。

3.建造

docker compose --profile auth build

4.身份验证

docker compose --profile auth run --rm --service-ports auth

打开http://localhost:8901，如果需要，请输入电话、代码和2FA密码。

5.选择运输方式

选项A:stdio（默认，每个客户端一个进程）

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "compose", "-f", "/path/to/telegram-mcp/docker-compose.yml",
        "run", "--rm", "-i", "--no-deps", "--service-ports", "mcp"
      ]
    }
  }
}

mcp 服务被固定到 --transport stdio 在 docker-compose.yml.

如果以前 mcp 一次性容器仍在运行，一个新的 docker compose run 将失败 port is already allocated 上 8902.

选项B:SSE（共享长期服务器）

启动后台SSE服务器：

docker compose --profile sse up -d mcp-sse

终点：

  • MCP SSE端点： http://localhost:8903/sse
  • 媒体代理终结点： http://localhost:8904/media/{token}

Claude代码示例：

{
  "mcpServers": {
    "telegram-sse": {
      "type": "sse",
      "url": "http://localhost:8903/sse"
    }
  }
}

停止SSE服务器：

docker compose --profile sse stop mcp-sse
docker compose --profile sse rm -f mcp-sse

选项C：Codex的流式HTTP（共享长期服务器）

启动后台HTTP服务器：

docker compose --profile http up -d mcp-http

终点：

  • MCP端点： http://localhost:8905/mcp
  • 媒体代理终结点： http://localhost:8906/media/{token}

食品法典示例：

codex mcp add telegram --url http://localhost:8905/mcp

停止HTTP服务器：

docker compose --profile http stop mcp-http
docker compose --profile http rm -f mcp-http

建筑

flowchart LR
  MCP["presentation (MCP tools)"] --> APP["application (use-cases)"]
  APP --> DOMAIN["domain (models, errors, ports)"]
  APP --> INFRA["infrastructure (Telethon adapter)"]
  AUTH["auth web UI"] --> INFRA

层：

  • domain/：实体、值对象、错误模型、读取端口。
  • application/：用例、验证、游标编解码器、响应信封。
  • infrastructure/：基于Telethon的实现和提供程序错误映射。
  • presentation/：MCP工具曝光和标记渲染。
  • auth/：web流仅用于授权。

发展和质量门

python3 -m pip install -e .[dev]
ruff check .
mypy
pytest -q

CI运行相同的闸门 docker compose config 烟雾检查。

突变边界

此项目不公开发送/编辑/删除消息工具。 唯一的写入操作是显式成员身份操作：

  • unsubscribe_from_channel
  • leave_chat

相关 MCP