areweai/tsgram-mcp

分类General
作者Community
星标458
定价Free

简介

tsgram-mcp 是一个将 Telegram 转化为 Claude 移动端“工作站”的桥接工具。它通过 MCP 协议，让用户在手机端通过 Telegram 机器人就能调用 Claude 的能力，并直接读写本地工作区代码。简单来说，它解决了 AI 助手在移动端缺乏本地文件操作权限的痛点，让开发者在通勤或碎片时间也能进行轻量级的代码修改和项目维护。对于习惯使用 TypeScript 的开发者，其上手难度较低，是将 LLM 能力无缝集成到即时通讯工具中的典型实践。

核心亮点

  • 将 Telegram 变为 Claude 的移动端代码编辑器
  • 支持在手机上直接读写本地工作区文件
  • 基于 TypeScript 开发，扩展性强且易于部署
  • 打破移动端 AI 无法操作本地文件的限制

完整文档

TSGram MCP 🚀

在 3 分钟内让本地项目中的 Claude Code 与 Telegram 连通！

<img src="assets/IMG_3908.PNG" alt="TSGram in action - viewing package.json" height="450">

TSGram MCP 使用 TS/Node/Docker/cli-utils 将 Claude Code 会话连接到 Telegram，从而在 Telegram 聊天中直接实现 AI 驱动的代码辅助。你可以通过手机上的 Telegram 询问关于代码库的问题、获取 AI 洞察，甚至编辑文件！

🔒 工作原理（全部本地化）

  • 本地 Docker 容器运行 Telegram webhook 服务器
  • TSGram MCP server 在本地运行
  • 你的 Claude Code 或 Claude Desktop 在本地运行并本地添加 MCP
  • 通过 Telegram 在应用内创建和删除 bots，访问权限仅限于你的 telegram user id
  • 现代化的本地 Web 仪表盘，可通过 localhost 管理 bots
  • 本地即意味着本地！如果你的计算机离线，你的 bots 也会离线。

快速上手（3 分钟）

🤖 AI Agent 增强安装（推荐！）

让 Claude 处理整个安装过程并向你询问所需的值。

在终端执行：
0. 安装 Docker Desktop 和 Node.js 20+（包含 npm）
1. 克隆仓库：

bash
git clone https://github.com/areweai/tsgram-mcp.git
   cd tsgram-mcp
2. 从命令行启动 Claude：
bash
claude --model sonnet
3. 使用 /init 进行初始化

4. 复制并粘贴此 prompt：
> 首先，向用户解释如何通过 @BotFather 注册一个新的 Telegram bot 并获取 bot token (TELEGRAM_BOT_TOKEN)，以及如何通过 @userinfobot 获取 Telegram 用户 ID（用于 AUTHORIZED_CHAT_ID）。在你在设置系统时，他们可以同步获取这些凭据。然后帮助用户为 claude code 设置 tsgram-mcp。完成从安装 node modules 到创建并部署本地 docker containers 的所有步骤。最后，当所有内容部署完成后，提醒用户配置其 bot token、authorized chat ID 以及其他必需的 .env 变量。

请确保将 TELEGRAM_BOT_TOKEN 和 AUTHORIZED_CHAT_ID 占位符替换为实际值。

为了获取这些值，你需要向以下 Telegram bots 发送消息并按照其指令操作：


随后 AI 将为你处理所有设置步骤，包括：

  • 安装依赖

  • 配置环境变量

  • 构建 Docker containers

  • 启动服务

  • 指导你完成 bot 注册

  • 设置 MCP server（并允许你在本地扩展功能）

如果遇到 LLM 问题，可使用 CLI 非 AI 替代方案：设置 Shell 脚本
在项目根目录下运行：

bash
# One-line install (macOS/Linux)
curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh | bash


Or if you prefer to review first:

curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh > setup.sh
chmod +x setup.sh
./setup.sh
将 TSGram 添加到现有项目：

如果你已经有一个项目并想将 TSGram 作为 MCP server 添加进来：

1. 在现有项目的根目录下：

bash
git clone https://github.com/areweai/tsgram-mcp.git .tsgram-mcp
   cd .tsgram-mcp
2. 使用 Claude 进行设置：
bash
claude model --sonnet
   /init
3. 粘贴此提示词：
> "首先，向用户解释如何通过 @BotFather 注册一个新的 Telegram bot 并从 @UserBotInfoBot 获取 bot token (TELEGRAM_BOT_TOKEN)，以及如何从 @userinfobot 获取 Telegram 用户 ID (用于 AUTHORIZED_CHAT_ID)。在设置系统期间，他们可以先准备这些凭据。然后帮我将 TSGram MCP 添加到父目录中的现有项目中。配置 Docker 容器和 MCP 配置，以便我可以使用 Telegram 与项目文件进行交互。项目根目录在当前目录的上一级。"

这将配置 TSGram 与您现有的项目结构协同工作（并允许您在本地扩展功能）。

测试您的 Bot！🎉

重要提示：您需要先向您的 bot 发送消息，它才能给您发送消息。

向您的 bot 发送一条消息，询问关于您本地项目的问题！

<img src="assets/IMG_3913.PNG" alt="TSGram file permissions and dangerzone mode" height="450">

⚠️ 安全注意事项：TSGram 具有基础的保护机制，不会列出、预览或提供 .env 文件，但由于第三方服务器参与了传输层，仍强烈建议不要将 TSGram 用于处理高度敏感的数据。

📊 Web Dashboard

通过美观的 Web Dashboard 监控和管理您的 bot，访问地址：http://localhost:3000

<img src="assets/tsgram-dashboard-1.png" alt="TSGram Web Dashboard - Bot management interface" width="600">仪表盘提供：

  • 实时 bot 状态与活动监控

  • 系统健康指标 (MCP server, AI model, API keys)

  • Bot 管理 - 创建、测试并监控 Telegram bots

  • 活动日志 - 追踪消息、响应和系统事件

  • 快速操作 - 发送测试消息并管理 bot 配置

  • 本地运行 - 执行 npm run dashboard 查看（推荐使用 Chrome）

📋 你需要准备

  • 手机端 Telegram
  • Claude Desktop 或 Claude Code (CLI)
  • 一个 OpenRouter API key（建议创建额度为 $1.00 的新 API key。信任，但要限制！）
  • Chrome（可选，但强烈推荐用于本地管理 UI）

手动安装步骤

1. 获取 Bot Token 和 User ID

1. 创建 Bot：在 Telegram 上给 @BotFather 发消息 2. 发送 /newbot 并按照提示操作 3. 复制你的 bot token（请务必保密！） 4. 获取你的 User ID（重要）：给 @userinfobot 发消息 - 这将返回你的数字 user ID（例如 123456789） - 出于安全考虑，请使用 user ID 而非用户名（用户名是可以更改的）

2. 配置环境

编辑 .env 文件并填写你的数值：
env
TELEGRAM_BOT_TOKEN=your_bot_token_here

CRITICAL: Use your numeric user ID from @userinfobot, not your username!

AUTHORIZED_CHAT_ID=123456789  # Your numeric user ID from step 1

Choose ONE AI provider:

OPENROUTER_API_KEY=your_openrouter_key  # For Claude (recommended with $1 limit)

OR

OPENAI_API_KEY=your_openai_key         # For GPT-4
安全注意事项：Bot 现在使用您的数字用户 ID 而非用户名进行授权。这样做更安全，因为：
  • 用户 ID 永不改变
  • 用户名可以被用户更改
  • 用户 ID 无法被猜测或轻易发现

3. 启动 TSGram
bash
npm install

npm run docker:build npm run docker:start
## 🎯 核心特性
  • TSGram bot 聊天中的 "Stop" 和 "Start" 命令 提供便捷的输出控制
  • 选择支持的 unix 命令子集 (:h ls 或 :h cat $FILE)
  • 可选的编辑模式，用于随时进行 vibe coding 和调试（使用 :dangerzone 启用）
  • AI 驱动的响应：使用 Claude 3.5 Sonnet 或 GPT-4
  • 代码理解：读取并分析你的整个 codebase
  • Web Dashboard：在 http://localhost:3000 监控 bots

💬 Bot 命令

  • 普通消息：获取关于代码的 AI 响应
  • :h - 显示帮助和可用命令
  • :h ls [path] - 列出目录中的文件
  • :h cat filename - 查看文件内容
  • :dangerzone - 启用文件编辑（请小心！）
  • :safetyzone - 禁用文件编辑
  • stop - 暂停 bot 响应
  • start - 恢复 bot 响应

🛠️ 常用命令
bash
# View logs

npm run docker:logs

Check health

npm run docker:health

Stop services

npm run docker:stop

Rebuild after changes

npm run docker:rebuild

Access dashboard (Chrome recommended)

npm run dashboard
## 📜 实用脚本

项目在 scripts/ 目录下包含多个辅助脚本：

安装与配置



更新与维护


测试与调试


运行任何脚本请使用：

bash
./scripts/script-name.sh
or

npm run script-name  # for npm-wrapped scripts
## 🔧 高级设置

与 Claude Code 配合使用

添加到你的 Claude Code MCP 设置中：
json
{
  "tsgram": {
    "command": "docker",
    "args": ["exec", "-i", "tsgram-mcp-workspace", "npx", "tsx", "src/mcp-server.ts"],
    "env": {
      "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
      "AUTHORIZED_CHAT_ID": "123456789"
    }
  }
}
注意：将 123456789 替换为从 @userinfobot 获取的实际数字 user ID

MCP 兼容性

TSGram 使用标准的 Model Context Protocol (MCP) 格式，应与任何支持 MCP 的 IDE 或工具兼容。已测试：


应支持（标准 MCP 格式）：



请使用上述相同的 Docker 配置模式，并根据您具体的 MCP 客户端调整语法。

CLI-to-Telegram 桥接

将 Claude Code CLI 的响应转发至 Telegram：
bash
# Setup global command (may prompt for sudo password to create npm global install /usr/local/bin/claude-tg)
npm run setup

Use instead of 'claude'

claude-tg "analyze this codebase"
## 🚨 故障排除

Bot 没有响应？

bash
# Check if services are running
npm run docker:health


View logs for errors

npm run docker:logs
无法连接到 bot？ 1. 验证 .env 中的 bot token 是否正确 2. 检查您的用户 ID：确保 AUTHORIZED_CHAT_ID 是您的数字用户 ID（而非用户名） - 如不确定，请通过 @userinfobot 获取 3. 确保您已先向 bot 发送消息 4. 如果出现 "authorization not configured" 错误，请在 .env 文件中设置 AUTHORIZED_CHAT_ID

文件编辑无效？



📚 项目结构
code
tsgram/

├── src/ │ ├── telegram-bot-ai-powered.ts # Main bot logic │ ├── telegram-mcp-webhook-server.ts # MCP integration │ └── models/ # AI providers ├── docker-compose.tsgram-workspace.yml # Main Docker config ├── .env.example # Environment template └── data/ # Persistent storage## 🤝 Contributing

欢迎提交 PR！请：
1. Fork 本仓库
2. 创建 feature 分支
3. 如适用，请添加测试
4. 提交 pull request

📄 License

MIT - 欢迎在你的项目中自由使用！

---

需要帮助？ 在 GitHub 上提交 issue 或向你的 bot 发送问题！

查看官方来源