使用说明

MCP电报

Telegram MCP Server for Claude Code, Cursor, and AI Agents

Send messages, files, voice notes via Telegram from your AI assistant

为什么选择MCP Telegram？

通过Telegram远程访问您的计算机。 让克劳德给你发送文件、截图、代码片段或语音信息——在Telegram中立即接收。在任何地方工作。

像你自己一样发送消息。 与机器人不同，MTProto从您的个人帐户发送。直接通过克劳德给朋友、同事或业务联系人发消息。

双向沟通。 通过机器人向Claude发送命令，接收结果。非常适合无头服务器或远程开发。

📱 个人账户（MTProto） --通过Telegram发送消息、文件和语音
🤖 博特API --双向克劳德↔ 您的沟通渠道
📁 文件传输 --发送/接收文档、照片、语音信息
🎤 语音信息 --完整的语音备忘支持（发送和接收）
🔧 三个接口 -MCP（用于AI）、CLI（用于人类）、HTTP API（用于脚本）
🏗️ Daemon架构 --解决AI会话之间的SQLite会话锁定问题
🔒 安全 --凭据存储在本地，守护进程仅在本地主机上监听

用例

远程文件访问

You: "Send me the latest build log"
Claude: *sends /var/log/build.log to your Telegram*

语音通知

You: "When tests finish, send me a voice message with results"
Claude: *runs tests, generates voice summary, sends to Telegram*

给任何人留言

You: "Send @colleague the updated API documentation"
Claude: *sends message from YOUR account to @colleague*

双向通信

[In Telegram] You: "Check server status"
[Bot receives] Claude: *runs diagnostics, sends report back*

快速开始

1.安装

# With uv (recommended)
uv tool install mcp-telegram

# With pip
pip install mcp-telegram

# From source
git clone https://github.com/antongsm/mcp-telegram
cd mcp-telegram
uv sync

2.设置

tg login

向导将指导您完成以下操作：

MTProto设置 -从获取API凭据 my.telegram.org/apps
机器人设置（可选） --通过以下方式创建机器人 @植物学家

3.启动守护进程

tg daemon start

4.添加到克劳德代码

claude mcp add telegram -- tg mcp

就是这样！现在克劳德可以从你的电报中发送消息了。

建筑

┌─────────────────────────────────────────────────────────────┐
│                       Claude Code                            │
│                           ↓                                  │
│                    MCP Server (tg mcp)                       │
│                      ↓           ↓                           │
│          ┌──────────┴───┐   ┌───┴──────────┐                │
│          │   user_*     │   │    bot_*     │                │
│          │   tools      │   │    tools     │                │
│          └──────┬───────┘   └───────┬──────┘                │
│                 ↓                   ↓                        │
│          HTTP → Daemon        Direct HTTPS                   │
│                 ↓                   ↓                        │
│          Telegram MTProto    Telegram Bot API                │
│          (your account)      (@YourBot)                      │
└─────────────────────────────────────────────────────────────┘

为什么是守护进程？ Telethon使用SQLite进行会话存储。如果没有守护进程，多个Claude会话将相互锁定。守护进程拥有一个所有会话通过HTTP共享的单一连接。

CLI参考

设置和配置

tg login           # Interactive setup wizard
tg config          # Show current configuration
tg version         # Show version
tg tools           # List MCP tools

守护进程（MTProto）

tg daemon start    # Start in background
tg daemon start -f # Start in foreground
tg daemon stop     # Stop daemon
tg daemon status   # Check status
tg daemon logs     # View logs
tg daemon logs -f  # Follow logs
tg daemon restart  # Restart daemon

用户命令（MTProto）

发送消息 从您的帐户 对其他人：

# Send text
tg user send @username "Hello!"
tg user send +79001234567 "Hi there"

# Send file
tg user send-file @username /path/to/document.pdf
tg user send-file @username photo.jpg -c "Nice photo!"

# Send voice
tg user send-voice @username voice.ogg

# Read messages
tg user messages @username
tg user messages @username -n 20
tg user messages @username --json

# Search contacts
tg user dialogs
tg user dialogs -q "John"

# Download media
tg user download @username 12345 ~/Downloads/file.jpg

# Account info
tg user whoami

Bot命令（Bot API）

通信渠道 克劳德↔ 你:

# Send to default chat
tg bot send "Hello from Claude!"
tg bot send-file /path/to/file.pdf
tg bot send-photo /path/to/image.jpg
tg bot send-voice /path/to/voice.ogg

# Read messages from users
tg bot messages
tg bot messages -n 20

# Bot info
tg bot info

MCP工具

用户工具（MTProto）

工具	说明
`user_send_message`	从您的帐户发送文本
`user_send_file`	发送文件/照片/语音
`user_get_messages`	获取聊天记录
`user_search_dialogs`	搜索联系人/聊天记录
`user_download_media`	下载媒体
`user_edit_message`	编辑已发送的消息
`user_delete_messages`	删除邮件
`user_check_daemon`	检查守护进程状态

Bot工具（Bot API）

工具	说明
`bot_send_message`	通过机器人发送（克劳德→ 用户）
`bot_send_file`	通过机器人发送文件
`bot_send_photo`	通过机器人发送照片
`bot_send_voice`	通过机器人发送语音
`bot_get_messages`	获取传入消息
`bot_download_file`	按file_id下载文件

配置

所有配置存储在 ~/.mcp-telegram/:

~/.mcp-telegram/
├── config.json       # Credentials
├── session.session   # MTProto session
├── daemon.pid        # Daemon PID
├── daemon.log        # Daemon logs
└── downloads/        # Downloaded media

config.json结构

{
  "user": {
    "api_id": "12345678",
    "api_hash": "abcdef...",
    "phone": "+79001234567"
  },
  "bot": {
    "token": "123456:ABC-DEF...",
    "chat_id": "987654321"
  },
  "daemon": {
    "host": "127.0.0.1",
    "port": 19876
  }
}

获取凭据

步骤1:MTProto API（用户工具必需）

MTProto允许从您的个人Telegram帐户发送消息。

打开 my.telegram.org/apps 在浏览器中
登录使用您的电话号码（国际格式： +1234567890)
- 您将在Telegram应用程序中收到一个代码
- 在网站上输入代码
创建应用程序:
- 应用程序标题： MCP Telegram （或任何名称）
- 简称： mcptg （或任何名称）
- 平台： Other
- 说明：留空
复制凭据:
- App api_id → 这是你的 API ID （仅数字）
- App api_hash → 这是你的 API哈希 （32个字符）
运行安装向导:
```
tg login
```
输入API ID、API哈希和您的电话号码。验证码将发送到您的Telegram应用程序。

备注：API凭据与您的帐户绑定。保守秘密。它们允许完全访问您的Telegram。

步骤2：机器人令牌（Bot_*工具需要）

Bot API为您和Claude之间提供双向沟通渠道。

打开电报 并搜索 @植物学家
创建一个新的机器人:
```
/newbot
```
按照提示操作:
- 机器人名称： My Claude Bot （显示名称）
- 机器人用户名： my_claude_bot （必须以结尾 bot)
复制令牌:
```
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
```
获取您的聊天ID:
- 向您的新机器人发送任何消息
- 运行：
```
tg bot messages
```
- 注意 chat_id 从输出
或者使用curl：
```
curl "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'
```

添加到配置:

tg login  # Will prompt for bot token and chat_id

步骤3：首次登录

获取凭据后，运行安装向导：

tg login

向导将：

询问API ID、API哈希、电话（用于MTProto）
向您的Telegram应用程序发送验证码
请求Bot令牌和聊天ID（可选，用于Bot API）
将所有内容保存到 ~/.mcp-telegram/config.json

步骤4：验证设置

# Check MTProto connection
tg daemon start
tg user whoami
# Should show: Anton (@MT_nes) or your account

# Check Bot connection
tg bot info
# Should show your bot's name and username

# Test sending
tg user send me "Test from MTProto"
tg bot send "Test from Bot API"

自动启动（macOS）

创建 ~/Library/LaunchAgents/com.mcp.telegram.daemon.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.mcp.telegram.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/tg</string>
        <string>daemon</string>
        <string>start</string>
        <string>--foreground</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOU/.mcp-telegram/daemon.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOU/.mcp-telegram/daemon.stderr.log</string>
</dict>
</plist>

加载它：

launchctl load ~/Library/LaunchAgents/com.mcp.telegram.daemon.plist

自动启动（Linux）

systemd（Ubuntu、Debian、Fedora、CentOS、Arch）

创建 /etc/systemd/system/mcp-telegram.service:

[Unit]
Description=MCP Telegram Daemon
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
Environment="PATH=/home/YOUR_USERNAME/.local/bin:/usr/local/bin:/usr/bin"
ExecStart=/home/YOUR_USERNAME/.local/bin/tg daemon start --foreground
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动：

# Replace YOUR_USERNAME with your actual username
sudo systemctl daemon-reload
sudo systemctl enable mcp-telegram
sudo systemctl start mcp-telegram

# Check status
sudo systemctl status mcp-telegram

# View logs
sudo journalctl -u mcp-telegram -f

用户级systemd（无需sudo）

创建 ~/.config/systemd/user/mcp-telegram.service:

[Unit]
Description=MCP Telegram Daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/tg daemon start --foreground
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

启用并启动：

systemctl --user daemon-reload
systemctl --user enable mcp-telegram
systemctl --user start mcp-telegram

# Enable lingering (keeps service running after logout)
loginctl enable-linger $USER

# Check status
systemctl --user status mcp-telegram

Docker（任何Linux）

FROM python:3.12-slim

RUN pip install mcp-telegram

COPY config.json /root/.mcp-telegram/config.json
COPY session.session /root/.mcp-telegram/session.session

EXPOSE 19876

CMD ["tg", "daemon", "start", "--foreground"]

docker build -t mcp-telegram .
docker run -d --name mcp-telegram -p 127.0.0.1:19876:19876 mcp-telegram

备注：对于Docker，你需要复制 session.session 从您已经登录的机器上，因为登录过程需要交互式输入。

主管（遗留系统）

创建 /etc/supervisor/conf.d/mcp-telegram.conf:

[program:mcp-telegram]
command=/home/YOUR_USERNAME/.local/bin/tg daemon start --foreground
directory=/home/YOUR_USERNAME
user=YOUR_USERNAME
autostart=true
autorestart=true
stderr_logfile=/var/log/mcp-telegram.err.log
stdout_logfile=/var/log/mcp-telegram.out.log

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mcp-telegram

安全

本项目的设计考虑了安全性：

仅限本地凭据 -API密钥存储在 ~/.mcp-telegram/config.json，除了Telegram，从未传输过
本地主机守护进程 --HTTP服务器绑定到 127.0.0.1 只有，无法从网络访问
无数据收集 --无分析、无遥测、无外部服务
默认情况下为只读 --删除操作需要明确的消息ID
开源 --提供完整的代码审核

代码没有做什么：

不会删除您的帐户或联系人
不发送垃圾邮件或批量邮件
不会将凭据暴露给第三方
没有隐藏的后门
没有明确的命令，无法访问聊天

故障排除

守护进程未启动

# Check logs
tg daemon logs

# Check if port is in use
lsof -i :19876

# Kill stale processes
pkill -f "mcp_telegram.daemon"

会话已过期

# Re-login
tg login

数据库已锁定（SQLite错误）

这不应该发生在守护进程架构中。如果是这样：

# Stop all processes
tg daemon stop
pkill -f "mcp_telegram"

# Restart
tg daemon start

发展

# Clone
git clone https://github.com/antongsm/mcp-telegram
cd mcp-telegram

# Install with dev deps
uv sync --dev

# Run tests
uv run pytest

# Lint
uv run ruff check .
uv run ruff format .

# Type check
uv run pyright

许可证

麻省理工学院

关键词

mcp telegram claude claude-code cursor ai-agent mtproto bot-api telethon model-context-protocol llm ai-assistant file-transfer voice-messages remote-access automation

学分

最初的MTProto实施叶布西拉 Driba
通过以下方式统一守护进程架构安东·诺兹德林
内置于电话马拉松和主控程序

Made with Claude Code by Yeabsira Driba & Anton Nozdrin