MCP Telegram

mcp-telegram

适用于 Claude、Codex、Cursor、Claude Code、VS Code、Cline、Windsurf 及其他 MCP 客户端的 Telegram MCP 服务。通过 MTProto 使用真实的 Telegram 用户账号，基于浏览器在本地登录，提供 100 多种工具。需要延迟加载并降低上下文开销？请查看基于技能的配套项目 telegram-agent。

一个 Model Context Protocol（MCP）服务，通过 MTProto 将 Claude Desktop、Codex CLI、Cursor、Claude Code、VS Code、Cline、Windsurf、Goose 及任何其他兼容 MCP 的客户端连接到真实的 Telegram 用户账号，让你的 Agent 可以通过聊天或自动化工具调用来读取、搜索、发送、管理和维护 Telegram 聊天，而不必在 Telegram 界面中逐一点击。

**可用于：**读取对话并全局搜索消息 · 发送／编辑／转发／回应／发起投票 · 下载媒体并转录语音留言 · 管理频道（封禁／限制／提升权限、邀请链接、慢速模式、管理员日志、论坛话题）· 管理动态、联系人、草稿、通知、文件夹、隐私 · 或使用原始 MTProto 桥接处理其他任何事项。所有操作均通过一个已登录的用户账号进行，无需机器人。

警告

此服务以真实的 Telegram 用户身份（而非机器人）登录。会话存储在 ~/.telegram-agent/ 中。请像保护密码一样保护此目录。

先决条件

1. Node.js >=20
2. 从 my.telegram.org/apps 获取 Telegram API 凭据：api_id 和 api_hash

想要更轻量的传输方式？

此软件包是 MCP 服务——每轮对话中，所有工具的 schema（约 12,700 个 token）都会占用 Agent 的上下文。它适用于任何 MCP 客户端，也适用于无法执行 shell 命令的托管运行时。

如果你的 Agent 是 Claude Code / Codex CLI / Cursor / Gemini CLI / Cline / Windsurf，可以使用配套软件包 telegram-agent，它将相同的 Telegram 功能作为通用 Agent 技能提供。只有当提示词提及 Telegram 时，Agent 才会加载技能说明——空闲时上下文开销降低约 50 倍。它可独立运行（无需 MCP 服务参与），但与此软件包共用 ~/.telegram-agent/ 会话存储——登录一次，即可任选其一或同时使用两者。

npm i -g telegram-agent
telegram-agent login
npx skills add beautyfree/telegram-agent -a claude-code -g

MCP 安装方式请见下文。

安装

选项 A——自动配置所有客户端：

npx add-mcp mcp-telegram \
  --env TELEGRAM_API_ID=123456 \
  --env TELEGRAM_API_HASH=abc...

add-mcp（来自 Neon）会为 Claude Desktop、Claude Code、Cursor、VS Code、Codex、Gemini CLI、Cline、Zed、Goose、OpenCode 等客户端写入正确的配置。请在交互式提示中选择客户端。

重要

两个环境变量均为必填项。请从 my.telegram.org/apps 获取。

选项 B——手动配置：

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

claude mcp add telegram \
  -e TELEGRAM_API_ID=123456 \
  -e TELEGRAM_API_HASH=abc... \
  -- npx -y mcp-telegram

[mcp_servers.telegram]
command = "npx"
args = ["-y", "mcp-telegram"]
env = { TELEGRAM_API_ID = "123456", TELEGRAM_API_HASH = "abc..." }

向你的 Agent 询问：

登录我的 Telegram。

Agent 会调用 login 工具。浏览器标签页会打开。输入你的电话号码、短信验证码，以及（如果设置了）2FA 密码。标签页会显示绿色勾号，此时可以关闭它。会话现已存储在本地，Agent 可以读取你的 Telegram。

若要添加另一个账号，请让 Agent 再次调用 login。

工具

102 个工具，覆盖 Telegram 用户账号的全部功能。下面列出常用工具，其余工具归类在可折叠区域中。每个工具都接受可选的 accountId（如果只登录了一个账号，则可省略）。peer 接受数字聊天 ID、@username 或字面值 "me"（已保存的消息）。

菜单顶部：

控制开放的工具

三个环境变量，按顺序应用：

示例：

MCP_TELEGRAM_READONLY=1                                    # read-only agent
MCP_TELEGRAM_TOOLS='login,list*,search*,get*'              # discovery-only
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'  # safer write set

环境

选择 Agent 可见的工具

这三个门控变量依次生效：MCP_TELEGRAM_READONLY → MCP_TELEGRAM_TOOLS → MCP_TELEGRAM_DISABLE。

# Read-only agent — every mutating tool is hidden
MCP_TELEGRAM_READONLY=1

# Discovery-only — only login + the list/search/get tools
MCP_TELEGRAM_TOOLS='login,list*,search*,get*,resolveUsername'

# Allow writes but keep destructive ones away from the agent
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'

# Specific surface: read + send/edit only
MCP_TELEGRAM_TOOLS='login,list_accounts,list_dialogs,list_messages,search_messages,search_global,send_message,editMessage'

在 MCP 客户端配置中，将这些变量加入与 TELEGRAM_API_ID/TELEGRAM_API_HASH 相同的 env 块。若要验证，请重新打开客户端——服务器公布的工具，正是门控生效后注册的工具。

数据布局

~/.telegram-agent/
├── state.json          known accounts (no secrets in here)
└── sessions/
    └── <account_id>/   per-account MTProto session

如果 Telegram 会话在服务器端失效（在另一台设备上退出登录、密码轮换等），下一次工具调用会返回错误，提示 Agent 调用 login 重新授权。

开发

git clone https://github.com/beautyfree/mcp-telegram
cd mcp-telegram
npm install
echo "TELEGRAM_API_ID=...\nTELEGRAM_API_HASH=..." > .env
npm run dev

布局：

src/
├── index.ts           bin entry — stdio MCP server, tool registrations
├── telegram.ts        MTProto client + login state machine
├── auth-browser.ts    ephemeral HTTP server that drives the browser flow
├── auth-page.ts       inline HTML for the auth page
├── state.ts           persistent state in ~/.telegram-agent/
└── logger.ts

许可证

MIT — 请参阅 LICENSE。