areweai/tsgram-mcp

**Get Claude Code in your local project talking to Telegram in 3 minutes!**
TSGram MCP connects Claude Code sessions to Telegram using TS/Node/Docker/cli-utils, enabling AI-powered code assistance directly in your Telegram chats. Ask questions about your codebase, get AI insights, and even edit files - all from Telegram on your phone!
🔒 How It Works (All Local)
- Local Docker container runs the Telegram webhook server
- TSGram MCP server runs locally
- Your Claude Code or Claude Desktop runs locally and adds MCP locally
- Create and delete bots in-app through Telegram, access limited to your telegram user id
- Modern local web dashboard to manage bots from localhost
- Local means local! If your computer is offline, so are your bots.
Quick Start (3 Minutes)
🤖 AI Agent Enhanced Setup (Recommended!)
Let Claude handle the entire setup and ask you for the required values.
**From your terminal:**
0. Install Docker Desktop and Node.js 20+ (npm included)
1. Clone the repository:
2. From the command line, start Claude:
3. Initialize with /init
4. Copy and paste this prompt:
> First, explain to the human how to register a new Telegram bot with @BotFather and get their bot token (TELEGRAM_BOT_TOKEN), and how to get their Telegram user ID from @userinfobot (for AUTHORIZED_CHAT_ID). They can work on getting these credentials while you set up the system. Then help the user set up tsgram-mcp for claude code. Do everything from installing node modules to creating and deploying the local docker containers. Finally, when everything is deployed, remind the user to configure their bot token and authorized chat ID along wither other required .env variables.
Make sure you replace the TELEGRAM_BOT_TOKEN and AUTHORIZED_CHAT_ID placeholders with the actual values.
In order to retrieve those values, you will have to message the following Telegram bots and follow their instructions:
- @BotFather
- @userinfobot
The AI will then handle all the setup steps for you, including:
- Installing dependencies
- Configuring environment variables
- Building Docker containers
- Starting services
- Guiding you through bot registration
- Setting up the MCP server (and allow you to extend functionality locally)
**CLI no-AI Alternative If Hitting LLM troubles: Setup Shell Script**
Run from your project root:
**Adding TSGram to an Existing Project:**
If you already have a project and want to add TSGram as an MCP server:
1. From your existing project root:
2. Use Claude to set it up:
3. Paste this prompt:
> "First, explain to the human how to register a new Telegram bot with @BotFather and get their bot token (TELEGRAM_BOT_TOKEN) from @UserBotInfoBot, and how to get their Telegram user ID from @userinfobot (for AUTHORIZED_CHAT_ID). They can work on getting these credentials while you set up the system. Then help me add TSGram MCP to my existing project in the parent directory. Set up the Docker containers and MCP configuration so I can use Telegram to interact with my project files. The project root is one level up from here."
This will configure TSGram to work with your existing project structure (and allow you to extend functionality locally).
Test Your Bot! 🎉
**IMPORTANT: You will need to message your bot first before it can message you.**
Send your bot a message and ask it something about your local project!
**⚠️ Security Note**: TSGram has basic safeguards to not list, preview, or serve .env files but it is still strongly recommended that you do not use TSGram for anything highly sensitive as third party servers are part of the transport layer.