Skip to content
Back to search

tsgram-mcp

TSGram - Telegram MCP Server for local Claude Code integration - debug and vibe code on the go!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/areweai--tsgram-mcp/badge.svg)](/listings/areweai--tsgram-mcp)

HTML

<a href="/listings/areweai--tsgram-mcp"><img src="/api/listings/areweai--tsgram-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

πŸ€– 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](https://www.docker.com/products/docker-desktop/) and [Node.js 20+](https://nodejs.org/en/download) (npm included) 1. Clone the repository:

   git clone https://github.com/areweai/tsgram-mcp.git
   cd tsgram-mcp

2. From the command line, start Claude:

   claude --model sonnet

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](https://t.me/botfather) - [@userinfobot](https://t.me/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:

# 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

**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:

   git clone https://github.com/areweai/tsgram-mcp.git .tsgram-mcp
   cd .tsgram-mcp

2. Use Claude to set it up:

   claude model --sonnet
   /init

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 312 lines Β· 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.