内容
# mcp-telegram-local
一个**本地MCP（模型上下文协议）服务器**，通过MTProto将[Claude](https://claude.ai)连接到您的**个人Telegram账户**，使用与Telegram官方应用相同的加密协议。
Claude获得了11种工具和4种资源，可以读取消息、搜索聊天、发送回复、转发文件等，所有操作都通过您的真实Telegram账户完成，而非机器人。
```bash
npx mcp-telegram-local
```
---
## 与其他工具的不同之处
大多数Telegram集成使用Bot API，需要一个单独的机器人账户，无法访问您的个人聊天记录。而该服务器使用**MTProto**（通过[gramjs](https://github.com/gram-js/gramjs)）以**您**的身份登录，与官方Telegram桌面应用的工作方式相同。Claude看到的内容与您看到的内容完全相同：所有聊天记录、群组、频道、联系人以及消息历史。
---
## 隐私与安全
- **MTProto加密**：您计算机与Telegram服务器之间的所有流量都使用MTProto加密，这是Telegram自己的协议。从Telegram的角度来看，这只是您登录的另一个设备。
- **100%本地**：您的`api_id`、`api_hash`和会话文件仅存储在您的计算机上的`~/.mcp-telegram/`目录中，权限设置为`600`（仅所有者可读/写）。没有任何数据发送到Anthropic、npm或任何第三方，仅发送到Telegram自己的服务器。
- **Claude本地运行**：当Claude Code使用此服务器时，它会在您的机器上启动`npx mcp-telegram-local serve`作为本地进程。MCP通信通过stdio进行，没有打开网络端口，也没有数据离开您的计算机。
- **会话 = 登录**：保存的会话等效于登录的Telegram会话。请保持`~/.mcp-telegram/session.json`文件私密。如果需要撤销，请运行`npx mcp-telegram-local logout`，这将在Telegram侧注销会话并删除本地文件。
---
## 要求
- **Node.js 18或更高版本**
- **Telegram账户**
- **`api_id`和`api_hash`**来自[my.telegram.org](https://my.telegram.org) - 免费，2分钟即可获取（见下文）
---
## 快速开始
### 选项A - Web面板（推荐）
```bash
npx mcp-telegram-local ui
```
这将打开一个本地网页，地址为`http://127.0.0.1:8765`（仅在您的计算机上可访问）。从那里，您可以：
1. 输入您的`api_id`和`api_hash`
2. 通过**二维码**（用手机扫描）或**手机号码**（通过短信或Telegram发送代码）登录
3. 处理**2FA密码**（如果您已启用）
4. 点击**“添加到Claude Code”**以自动注册服务器
5. 立即查看可与Claude一起使用的示例提示
添加Claude Code后，请重启Claude Code并输入`/mcp` - 您应该会看到`telegram`列为已连接的服务器。
### 选项B - 终端登录
```bash
npx mcp-telegram-local auth
```
在终端中交互式地登录（打印手机号码或二维码为ASCII艺术），然后自动在Claude Code中注册服务器。
---
## 获取api_id和api_hash
您只需要获取一次。它们用于标识您的应用程序，并存储在本地。
1. 打开**https://my.telegram.org**并用您的手机号码登录
2. 点击**“API开发工具”**
3. 填写任意应用程序名称和简称（例如`MyApp` / `myapp`）- 值不重要
4. 复制 **`api_id`** （一个数字）和 **`api_hash`** （一个长十六进制字符串）
在提示时，将它们粘贴到Web面板或终端中。它们保存到`~/.mcp-telegram/config.json`中，以后不再需要。
---
## 所有命令
```bash
npx mcp-telegram-local # 显示此命令列表
npx mcp-telegram-local ui # ⭐ 打开Web控制面板
npx mcp-telegram-local auth # 通过终端登录并自动添加到Claude Code
npx mcp-telegram-local status # 检查会话是否有效
npx mcp-telegram-local add_mcp # 在Claude Code中注册服务器（无需重新登录）
npx mcp-telegram-local logout # 注销Telegram并删除本地会话
npx mcp-telegram-local delete_key # 删除api_id/api_hash并注销（完全重置）
npx mcp-telegram-local config # 打印Claude Code配置JSON片段
npx mcp-telegram-local serve # 强制MCP服务器模式在stdio上（由Claude使用）
npx mcp-telegram-local help # 显示帮助
```
---
## Claude Code如何使用此服务器
注册后，Claude Code会在需要访问Telegram时自动启动`npx mcp-telegram-local serve`作为后台进程。服务器通过**stdio**（标准输入/输出）使用MCP协议进行通信 - 没有Web服务器，没有打开的端口，也没有后台守护进程来管理。它按需启动，并在Claude完成后退出。
Claude Code存储的配置如下：
```json
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["mcp-telegram-local", "serve"]
}
}
}
```
您也可以通过运行以下命令手动添加：
```bash
claude mcp add --scope user telegram -- npx mcp-telegram-local serve
```
---
## 可用于Claude的MCP工具
| 工具 | 参数 | 功能 |
|---|---|---|
| `get_dialogs` | `limit`, `offset` | 列出您的聊天记录和频道 |
| `get_messages` | `chat_id`, `limit` | 从聊天记录中获取消息历史 |
| `search_messages` | `query`, `chat_id?`, `limit` | 在全局或特定聊天中搜索消息 |
| `get_unread` | `max_chats`, `max_messages_per_chat` | 获取所有聊天记录中的未读消息 |
| `send_message` | `chat_id`, `text` | 发送文本消息 |
| `reply_to_message` | `chat_id`, `message_id`, `text` | 回复特定消息 |
| `forward_message` | `from_chat`, `to_chat`, `message_id` | 在聊天记录中转发消息 |
| `download_file` | `chat_id`, `message_id`, `include_base64?` | 从消息中下载文件或照片 |
| `send_file` | `chat_id`, `file_path`, `caption?` | 从计算机发送文件 |
| `get_contacts` | — | 列出您的Telegram联系人 |
| `get_chat_members` | `chat_id`, `limit` | 列出群组或频道的成员 |
> `chat_id`接受数字ID、 `@username`或`t.me/...`链接。
## 可用于Claude的MCP资源
| URI | 描述 |
|---|---|
| `telegram://dialogs` | 所有对话/聊天记录 |
| `telegram://chat/{id}` | 具有近期消息的特定聊天记录 |
| `telegram://unread` | 所有未读消息 |
| `telegram://me` | 您的Telegram个人资料 |
---
## 您可以用Claude询问的内容
连接后，只需用纯英文描述您想要的内容：
- *"总结我与Alex的最近50条消息"*
- *"回复Maria，我将在7点钟到达"*
- *"显示所有未读消息，并告诉我哪些是紧急的"*
- *"在我的聊天记录中搜索任何关于合同的消息"*
- *"将来自@news_channel的最新消息转发到我的保存的消息"*
- *"将文件report.pdf发送到工作群组"*
- *"编写@somechannel过去一周帖子的摘要"*
- *"今天谁给我发消息了？"*
---
## 本地数据存储
所有数据都存储在本地，并具有限制性文件权限：
```
~/.mcp-telegram/
├── config.json # api_id 和 api_hash
├── session.json # gramjs 会话字符串（等效于 Telegram 登录）
└── downloads/ # 通过 download_file 工具下载的文件
```
要完全重置：
```bash
npx mcp-telegram-local delete_key
```
这会撤销Telegram服务器上的会话，删除`session.json`，并删除`config.json`。下次您将重新开始。
要仅注销（保留API凭证）：
```bash
npx mcp-telegram-local logout
```
注销后，请前往 **Telegram → 设置 → 设备** 以确认会话已被移除。
---
## 错误处理
- **会话过期**：如果您的会话过期（例如，您从另一台设备注销），工具将返回友好错误，并提供再次运行 `npx mcp-telegram-local auth` 的说明。
- **FLOOD_WAIT**：Telegram限制高频请求。短等待时间由gramjs自动处理；较长等待时间（最多5分钟）由内置包装器自动重试。
- **错误的2FA密码**：Web面板允许您重新输入2FA密码最多3次，然后放弃。终端登录也一样。
---
## 开发
```bash
git clone https://github.com/pokkop/mcp-telegram-local
cd mcp-telegram-local
npm install
npm run build # 编译TypeScript → dist/
npm run dev # 监视模式
node dist/index.js status
```
源代码布局：
```
src/
├── index.ts # 入口点：CLI命令 + stdio上的MCP服务器
├── auth.ts # 终端登录（手机+二维码），MTProto/隐私横幅
├── web.ts # 本地Web面板HTTP服务器 + gramjs登录桥
├── web-page.ts # 由web.ts提供的完整SPA（HTML/CSS/JS）
├── client.ts # TelegramClient包装器，JSON序列化器，注销
├── tools.ts # 所有11个MCP工具
├── resources.ts # 所有4个MCP资源
├── storage.ts # ~/.mcp-telegram/读写助手
├── claude.ts # 与Claude Code自动注册
├── notice.ts # 终端输出的英文MTProto/隐私通知
└── suppress-warnings.ts # 抑制gramjs的Node.js本地存储警告
```
TypeScript编译为ESM（`"type": "module"`），针对Node 18+。gramjs日志记录完全静音（`LogLevel.NONE`），以防止任何意外输出破坏MCP stdio流。
---
## License
MIT
