Telegram MCP服务器

mcp-telegram

Telegram MCP server for Claude, Codex, Cursor, Claude Code, VS Code, Cline, Windsurf, and other MCP clients. Real Telegram user account via MTProto, browser-based local sign-in, 100+ tools. Need lazy-loading + lower context cost? See telegram-agent, the skill-based companion.

A. 模型上下文协议 连接的（MCP）服务器 克劳德桌面版, Codex CLI, 光标, 克劳德代码、VS Code、Cline、Windsurf、Goose和任何其他MCP兼容客户端通过以下方式连接到真实的Telegram用户帐户 MTProto--因此，您的客服可以通过聊天或自动工具调用读取、搜索、发送、审核和管理Telegram聊天，而无需通过Telegram UI点击。

使用它来： 在全球范围内阅读对话框和搜索消息·发送/编辑/转发/反应/投票·下载媒体和转录语音笔记·适度频道（禁止/限制/推广、邀请链接、慢速模式、管理员日志、论坛主题）·管理故事、联系人、草稿、通知、文件夹、隐私·或通过原始MTProto桥进行其他任何操作。所有这些都只针对一个登录的用户帐户——不需要机器人。

[！警告] 此服务器以真实的Telegram用户（而非机器人）身份登录。会议直播 ~/.telegram-agent/。将该目录视为密码。

先决条件

1. Node.js >=20
2. 电报API凭证来自 my.telegram.org/apps — api_id 和 api_hash

想要更轻便的交通工具吗？

这个包裹是 MCP服务器 --每个工具模式（约12700个令牌）在每个回合都位于代理的上下文中。适用于任何MCP客户端和无法卸载的托管运行时。

如果你的代理人是 克劳德代码/Codex命令行界面/光标/双子座命令行界面/Cline/Windsurf，有一个 配套套餐-- telegram-agent --它运送的Telegram表面与 通用代理技能。只有当您的提示提到Telegram时，代理才会加载技能说明-- 约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等编写正确的配置。在交互式提示中选择客户端。

[！重要] 这两个env变量都是必需的。从以下位置获取它们 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..." }

首次登录

问你的经纪人：

登录我的Telegram。

代理人打电话给 login 工具。浏览器选项卡打开。输入您的电话号码、短信代码和2FA密码（如果有的话）。该选项卡显示一个绿色的复选标记——您可以关闭它。会话现在存储在本地，代理可以读取您的电报。

要添加另一个帐户，请代理人致电 login 再一次。

工具

102个工具覆盖了整个Telegram用户账户界面。下面是常见的；其余的则归为可坍塌类。每个工具都接受一个可选 accountId （当只有一个帐户登录时省略）。 peer 接受数字聊天id @username，或字面意思 "me" （已保存的消息）。

菜单顶部：

对暴露的工具进行门控

三个env变量，按顺序应用：

示例：

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

环境

选择代理看到的工具

三个门控变量堆叠-- 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客户端配置中，将这些放入相同的 env 块作为 TELEGRAM_API_ID/TELEGRAM_API_HASH。要验证，请重新打开客户端——服务器播发的工具正是gates运行后注册的工具。

数据布局

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

如果Telegram会话在服务器端无效（从另一个设备注销、密码轮换等），下一次工具调用将返回错误，告诉代理调用 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

许可证

麻省理工学院——见 许可证.