TSGram MCP 🚀

1# TSGram MCP 🚀
2 
3**Get Claude Code in your local project talking to Telegram in 3 minutes!**
4 
5<img src="assets/IMG_3908.PNG" alt="TSGram in action - viewing package.json" height="450">
6 
7TSGram 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!
8 
9## 🔒 How It Works (All Local)
10- Local Docker container runs the Telegram webhook server
11- TSGram MCP server runs locally 
12- Your Claude Code or Claude Desktop runs locally and adds MCP locally
13- Create and delete bots in-app through Telegram, access limited to your telegram user id
14- Modern local web dashboard to manage bots from localhost 
15- Local means local! If your computer is offline, so are your bots.
16 
17## Quick Start (3 Minutes)
18 
19### 🤖 AI Agent Enhanced Setup (Recommended!)
20 
21Let Claude handle the entire setup and ask you for the required values.
22 
23**From your terminal:**
240. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and [Node.js 20+](https://nodejs.org/en/download) (npm included)
251. Clone the repository:
26   ```bash
27   git clone https://github.com/areweai/tsgram-mcp.git
28   cd tsgram-mcp
29   ```
30 
312. From the command line, start Claude:
32   ```bash
33   claude --model sonnet
34   ```
35 
363. Initialize with `/init`
37 
384. Copy and paste this prompt:
39   > 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.
40 
41Make sure you replace the `TELEGRAM_BOT_TOKEN` and `AUTHORIZED_CHAT_ID` placeholders with the actual values.
42 
43In order to retrieve those values, you will have to message the following Telegram bots and follow their instructions:
44- [@BotFather](https://t.me/botfather)
45- [@userinfobot](https://t.me/userinfobot)
46 
47The AI will then handle all the setup steps for you, including:
48- Installing dependencies
49- Configuring environment variables
50- Building Docker containers
51- Starting services
52- Guiding you through bot registration
53- Setting up the MCP server (and allow you to extend functionality locally)
54 
55**CLI no-AI Alternative If Hitting LLM troubles: Setup Shell Script**
56Run from your project root:
57```bash
58# One-line install (macOS/Linux)
59curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh | bash
60 
61# Or if you prefer to review first:
62curl -sSL https://raw.githubusercontent.com/areweai/tsgram-mcp/main/setup.sh > setup.sh
63chmod +x setup.sh
64./setup.sh
65```
66 
67**Adding TSGram to an Existing Project:**
68 
69If you already have a project and want to add TSGram as an MCP server:
70 
711. From your existing project root:
72   ```bash
73   git clone https://github.com/areweai/tsgram-mcp.git .tsgram-mcp
74   cd .tsgram-mcp
75   ```
76 
772. Use Claude to set it up:
78   ```bash
79   claude model --sonnet
80   /init
81   ```
82 
833. Paste this prompt:
84   > "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."
85 
86This will configure TSGram to work with your existing project structure (and allow you to extend functionality locally).
87 
88### Test Your Bot! 🎉
89**IMPORTANT: You will need to message your bot first before it can message you.**
90 
91Send your bot a message and ask it something about your local project!
92 
93<img src="assets/IMG_3913.PNG" alt="TSGram file permissions and dangerzone mode" height="450">
94 
95 
96 
97**⚠️ 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.
98 
99## 📊 Web Dashboard
100 
101Monitor and manage your bots through the beautiful web dashboard at **http://localhost:3000**:
102 
103<img src="assets/tsgram-dashboard-1.png" alt="TSGram Web Dashboard - Bot management interface" width="600">
104 
105The dashboard provides:
106- **Real-time bot status** and activity monitoring
107- **System health** indicators (MCP server, AI model, API keys)
108- **Bot management** - create, test, and monitor Telegram bots
109- **Activity logs** - track messages, responses, and system events
110- **Quick actions** - send test messages and manage bot configurations
111- **run from local** - npm run dashboard to view (chrome recommended)
112 
113## 📋 You Will Need
114 
115- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
116- [Node.js 20+](https://nodejs.org/en/download) (npm included)
117- Telegram on a phone
118- Claude Desktop or Claude Code (CLI)
119- An OpenRouter API key (We recommend creating a new API key with a $1.00 limit. Trust, but limit!)
120- Chrome (Optional but highly recommended for local management UI)
121 
122## Manual Setup Steps
123 
124### 1. Get Your Bot Token & User ID
1251. **Create Bot**: Message [@BotFather](https://t.me/botfather) on Telegram
1262. Send `/newbot` and follow prompts
1273. Copy your bot token (keep this secret!)
1284. **Get Your User ID** (IMPORTANT): Message [@userinfobot](https://t.me/userinfobot)
129   - This returns your numeric user ID (e.g., `123456789`)
130   - **Use the user ID, NOT your username** for security (usernames can be changed)
131 
132### 2. Configure Environment
133Edit `.env` with your values:
134```env
135TELEGRAM_BOT_TOKEN=your_bot_token_here
136# CRITICAL: Use your numeric user ID from @userinfobot, not your username!
137AUTHORIZED_CHAT_ID=123456789  # Your numeric user ID from step 1
138 
139# Choose ONE AI provider:
140OPENROUTER_API_KEY=your_openrouter_key  # For Claude (recommended with $1 limit)
141# OR
142OPENAI_API_KEY=your_openai_key         # For GPT-4
143```
144 
145**Security Note**: The bot now uses your **numeric user ID** instead of username for authorization. This is more secure because:
146- User IDs never change
147- Usernames can be changed by users
148- User IDs cannot be guessed or easily discovered
149 
150### 3. Start TSGram
151```bash
152npm install
153npm run docker:build
154npm run docker:start
155```
156 
157## 🎯 Key Features
158 
159- **"Stop" and "Start" commands** in TSGram bot chat provide convenient output control
160- **Select subset of unix commands supported** (`:h ls` or `:h cat $FILE`)
161- **Opt-in edit mode** for vibe coding and debugging on the go (`:dangerzone` to enable)
162- **AI-Powered Responses**: Uses Claude 3.5 Sonnet or GPT-4
163- **Code Understanding**: Reads and analyzes your entire codebase
164- **Web Dashboard**: Monitor bots at http://localhost:3000
165 
166## 💬 Bot Commands
167 
168- **Regular messages**: Get AI responses about your code
169- **`:h`** - Show help and available commands
170- **`:h ls [path]`** - List files in directory
171- **`:h cat filename`** - View file contents
172- **`:dangerzone`** - Enable file editing (careful!)
173- **`:safetyzone`** - Disable file editing
174- **`stop`** - Pause bot responses
175- **`start`** - Resume bot responses
176 
177## 🛠️ Common Commands
178 
179```bash
180# View logs
181npm run docker:logs
182 
183# Check health
184npm run docker:health
185 
186# Stop services
187npm run docker:stop
188 
189# Rebuild after changes
190npm run docker:rebuild
191 
192# Access dashboard (Chrome recommended)
193npm run dashboard
194```
195 
196## 📜 Useful Scripts
197 
198The project includes several helper scripts in the `scripts/` directory:
199 
200**Setup & Configuration**
201- `setup.sh` - Automated install script (can be run via curl)
202- `configure-mcp.sh` - Configure MCP settings for Claude Desktop/Code
203- `fix-permissions.sh` - Fix file permissions if needed
204 
205**Updates & Maintenance**
206- `update-system.sh` - Update TSGram to latest version
207- `update-ai-context.sh` - Update AI context files
208 
209**Testing & Debugging**
210- `test-api-keys.sh` - Verify your API keys are working
211- `test-docker-setup.sh` - Test Docker configuration
212 
213Run any script with:
214```bash
215./scripts/script-name.sh
216# or
217npm run script-name  # for npm-wrapped scripts
218```
219 
220## 🔧 Advanced Setup
221 
222### Using with Claude Code
223Add to your Claude Code MCP settings:
224```json
225{
226  "tsgram": {
227    "command": "docker",
228    "args": ["exec", "-i", "tsgram-mcp-workspace", "npx", "tsx", "src/mcp-server.ts"],
229    "env": {
230      "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
231      "AUTHORIZED_CHAT_ID": "123456789"
232    }
233  }
234}
235```
236 
237**Note**: Replace `123456789` with your actual numeric user ID from [@userinfobot](https://t.me/userinfobot)
238 
239### MCP Compatibility
240 
241TSGram uses the standard Model Context Protocol (MCP) format and should be compatible with any MCP-supporting IDE or tool. **Tested with:**
242- ✅ Claude Code CLI
243- ✅ Claude Desktop
244 
245**Should work with** (standard MCP format):
246- Cursor IDE
247- GitHub Copilot
248- Other MCP-compatible editors
249 
250Use the same Docker configuration pattern shown above, adapting the syntax for your specific MCP client.
251 
252### CLI-to-Telegram Bridge
253Forward Claude Code CLI responses to Telegram:
254```bash
255# Setup global command (may prompt for sudo password to create npm global install /usr/local/bin/claude-tg)
256npm run setup
257 
258# Use instead of 'claude'
259claude-tg "analyze this codebase"
260```
261 
262## 🚨 Troubleshooting
263 
264**Bot not responding?**
265```bash
266# Check if services are running
267npm run docker:health
268 
269# View logs for errors
270npm run docker:logs
271```
272 
273**Can't connect to bot?**
2741. Verify bot token is correct in `.env`
2752. **Check your user ID**: Make sure `AUTHORIZED_CHAT_ID` is your numeric user ID (not username)
276   - Get it from [@userinfobot](https://t.me/userinfobot) if unsure
2773. Make sure you messaged the bot first
2784. If you get "authorization not configured" error, set `AUTHORIZED_CHAT_ID` in your `.env` file
279 
280**File edits not working?**
281- Type `:dangerzone` to enable (one-time)
282- Check logs for permission errors
283- Ensure Docker has file access
284 
285## 📚 Project Structure
286 
287```
288tsgram/
289├── src/
290│   ├── telegram-bot-ai-powered.ts    # Main bot logic
291│   ├── telegram-mcp-webhook-server.ts # MCP integration
292│   └── models/                        # AI providers
293├── docker-compose.tsgram-workspace.yml # Main Docker config
294├── .env.example                       # Environment template
295└── data/                             # Persistent storage
296```
297 
298## 🤝 Contributing
299 
300PRs welcome! Please:
3011. Fork the repository
3022. Create a feature branch
3033. Add tests if applicable
3044. Submit a pull request
305 
306## 📄 License
307 
308MIT - Feel free to use in your own projects!
309 
310---
311 
312**Need help?** Open an issue on GitHub or message your bot with questions!