Telegram MCP — 面向 AI 代理的本地只读访问

本地 MCP 服务器为 Codex、Claude 和其他 MCP 客户端提供三个工具：

服务器仅以只读方式运行。代码中不包含发送、编辑或删除消息的工具。服务器通过 STDIO 在本地运行，并且有意不提供网络 HTTP/SSE 访问。

支持的客户端

• ChatGPT/Codex Desktop；

• Codex CLI 和 IDE 扩展；

• Claude Code；

• Claude Desktop；

• 任何支持 STDIO 的本地 MCP 客户端。

本地服务器无法直接在 chatgpt.com、claude.ai、手机或其他计算机上运行：这些环境无法在您的机器上启动进程。

Related MCP server: tdl-mcp

环境要求

• Windows 10/11、macOS 或 Linux；

• Git；

• Python 3.10+；

• 至少一个受支持的 MCP 客户端。

新手安装指南

1. 打开终端

• macOS： Command + Space → 输入 Terminal → 回车。

• Windows：「开始」菜单 → 输入 PowerShell → 打开 PowerShell。

• Linux： 按 Ctrl + Alt + T 或打开 Terminal 应用。

2. 下载项目

macOS/Linux：

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell：

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

如果 GitHub 提示找不到仓库，说明您的账户目前没有访问该私有仓库的权限。

3. 获取 Telegram API ID 和 API Hash

1. 打开 my.telegram.org。

2. 使用手机号码登录。

3. 打开 API development tools。

4. 创建一个应用，例如 Local Telegram MCP。

5. 保存 api_id 和 api_hash。

请勿将 api_hash、登录验证码或云密码发送给 AI 聊天。

创建本地 .env 文件。

macOS/Linux：

cp .env.example .env
nano .env

在 Nano 中保存：Ctrl + O → 回车 → Ctrl + X。

Windows PowerShell：

Copy-Item .env.example .env
notepad .env

在本地填写文件：

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. 安装依赖并登录 Telegram

macOS/Linux：

bash setup.sh

Windows PowerShell：

powershell -ExecutionPolicy Bypass -File setup.ps1

脚本会自动查找 Python 3.10+、创建 .venv、安装依赖，并提示输入手机号码、Telegram 验证码以及（如果已启用）云密码。请仅在您自己的终端中输入这些信息。

连接到代理

在所有示例中，请使用 setup 脚本打印的绝对路径。命令是 .venv 中的 Python，参数是 telegram_mcp_server.py。

Codex CLI 和 ChatGPT/Codex Desktop

macOS/Linux：

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell：

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

在 ChatGPT/Codex Desktop 中，也可以打开 Settings → MCP servers → Add server，选择 STDIO 并填写相同的 Command 和 Arguments。保存后点击 Restart。同一 Codex 主机的本地客户端共享 ~/.codex/config.toml 配置。

Claude Code

macOS/Linux：

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell：

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

启动新的 Claude Code 会话并输入 /mcp。user 作用域使该服务器在该用户的不同本地项目中均可用。

Claude Desktop

打开 Developer/MCP 设置并添加本地 STDIO 服务器。如果您的 Claude Desktop 版本使用 JSON 配置，请添加该对象，同时保留其他服务器：

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

文件的常见位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json；

• Windows： %APPDATA%\Claude\claude_desktop_config.json。

完全重启 Claude Desktop 并打开一个新聊天。

其他 STDIO MCP 客户端

使用等效配置：

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

最终验证

请让代理执行：

使用 telegram list_chats，limit=10，并显示名称、类型和未读消息数。

在代理真正返回您的聊天列表之前，不要认为安装已完成。

多个账户

服务器支持独立的本地会话 default、work、personal 等。说明见 docs/MULTI_ACCOUNT.md。

面向 AI 代理的说明

如果由 Codex、Claude 或其他代理执行安装，请要求其完整阅读 docs/AGENT_SETUP.md 并逐步遵循。该文件记录了安全规则以及不同操作系统的分支情况。

安全与限制

• .env 和 sessions/ 已从 Git 中排除；

• .session 文件可访问您的账户——请勿复制或发布；

• 不下载媒体文件，仅返回 has_media 标志；

• 对 Telegram 的请求以您的账户身份执行，并受 Telegram 限制约束；

• 请勿同时使用同一个 .session 运行两个操作；

• 请勿将此服务器暴露到互联网。

更多详情：SECURITY.md。

故障排查

参见 docs/TROUBLESHOOTING.md。

开发

.venv/bin/python -m unittest discover -s tests -v

项目结构：

许可证

MIT — 项目可自由使用、修改和分发，但需保留版权声明和许可证文本。