SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingtsgram-mcp

tsgram-mcp

Use Claude with local workspace access from Telegram on your phone: read, write and code on the go.

Open website

About this tool

TSGram MCP is a Telegram MCP server used to integrate local Claude Code into Telegram, letting you debug and do vibe coding on your phone as well. It connects Claude Code sessions to Telegram via TS/Node/Docker/cli-utils, so you can get AI code assistance directly in Telegram chats: ask questions about the codebase, get AI insights, and even edit files.

Purpose

TSGram MCP's core purpose is to let developers interact with Claude Code in local projects through Telegram on their phones. It is suitable for users who need to view code, ask questions, or make lightweight edits in mobile scenarios. All processing is done locally: a local Docker container runs the Telegram webhook server, the TGram MCP server runs locally, and Claude Code or Claude Desktop also runs locally with MCP added locally. If the computer is offline, the bot will also be offline.

Main capabilities

  • Chat with local Claude Code sessions through Telegram and ask questions related to the codebase.
  • Supports reading, analyzing, and editing local project files (editing must be explicitly enabled).
  • Provides a local web dashboard (http://localhost:3000），可实时监控机器人状态、系统健康指标、活动日志，并创建、测试和管理 Telegram bot.
  • Supports creating and deleting bots within Telegram, with access restricted to your Telegram user ID.
  • Provides support for some Unix commands, such as :h ls、:h cat $FILE.
  • Provides :dangerzone to enable edit mode,:safetyzone to disable edit mode,stop and start to control bot responses.
  • Uses Claude 3.5 Sonnet or GPT-4 to generate AI responses.
  • Includes multiple helper scripts, such as setup.sh, configure-mcp.sh, fix-permissions.sh, update-system.sh, update-ai-context.sh, test-api-keys.sh, test-docker-setup.sh.

Usage

Quick start (about 3 minutes):

  1. Install Docker Desktop and Node.js 20+ (including npm).
  2. Clone the repository:git clone https://github.com/areweai/tsgram-mcp.git, then cd tsgram-mcp.
  3. Start Claude from the command line:claude --model sonnet.
  4. Use /init to initialize.
  5. Paste the provided prompt to let Claude assist with installing dependencies, configuring environment variables, building the Docker container, starting services, guiding bot registration, and setting up the MCP server.

Manual setup steps:

  1. Obtain the bot token and user ID: in Telegram, send /newbot to @BotFather and follow the prompts, then copy the bot token; send a message to @userinfobot to get the numeric user ID (for example, 123456789), and use the user ID instead of the username for authorization.
  2. Edit the .env file and fill in the corresponding values.
  3. Start TSGram.

Add TSGram to an existing project: In the root directory of the existing project, run git clone https://github.com/areweai/tsgram-mcp.git .tsgram-mcp, then cd .tsgram-mcp, use Claude setup and paste the corresponding prompt, configure the Docker container and MCP, and place the project root directory one level up.

Working with Claude Code: add TSGram to Claude Code's MCP settings, replacing 123456789 with the actual numeric user ID. TSGram uses the standard Model Context Protocol (MCP) format and has been tested to be compatible with Claude Code CLI and Claude Desktop; in theory, it also works with other MCP-supporting editors.

Use cases

  • Ask questions about a local codebase on your phone through Telegram.
  • Perform lightweight code editing and debugging in mobile scenarios (requires enabling :dangerzone).
  • Monitor and manage multiple Telegram bots through a local web dashboard.
  • Forward Claude Code CLI responses to Telegram.

Limitations and Security Notes

  • All services run locally; the bot is unavailable when the computer is offline.
  • Requires Node.js 20+, Telegram mobile, Claude Desktop or Claude Code (CLI), an OpenRouter API key (creating a key with a $1 limit is recommended); Chrome is optional but recommended for the local management interface.
  • TSGram has basic protections and will not list, preview, or provide the .env file, but because third-party servers are part of the transport layer, it is strongly recommended not to use it for highly sensitive content.
  • Authorization uses numeric user IDs rather than usernames, because user IDs are immutable and hard to guess.
  • On first use, you must send a message to the bot before the bot can reply to you.
  • File editing requires entering :dangerzone to enable it once.
  • If an "authorization not configured" error occurs, you need to set AUTHORIZED_CHAT_ID in .env .
  • The project uses the MIT license.

Related tools

Browse category