Tsgram MCP

What areweai/tsgram-mcp MCP server does

The areweai/tsgram-mcp MCP server connects Telegram with a local development workspace used by Claude Code or Claude Desktop. From a Telegram chat, an authorized user can ask questions about the project and receive AI-generated responses based on the codebase. The system also supports file inspection through helper commands and an optional editing mode for coding and debugging tasks.

Access is restricted using a numeric Telegram user ID. The bot must receive an initial message from the user before it can send messages back. Bot creation and removal can be handled through Telegram, while a local web dashboard at http://localhost:3000 provides bot management, status information, health indicators, activity logs, and test actions.

How it works

The application is intended to run locally. A Docker container hosts the Telegram webhook service, while the MCP server runs locally and is added to the local Claude configuration. The local project files remain available to the coding session, but Telegram is part of the transport path. If the computer running the services is offline, the bots are also unavailable.

The bot accepts ordinary questions as well as command-style messages. :h displays help, :h ls [path] lists files, and :h cat filename displays a file. stop pauses responses and start resumes them. Editing is disabled by default and can be enabled with :dangerzone; :safetyzone disables it again.

Setup and configuration

Running the areweai/tsgram-mcp MCP server requires Docker Desktop, Node.js 20 or later, npm, Telegram, and Claude Desktop or Claude Code. The repository can be cloned locally, dependencies installed, and the Docker services built and started with the project’s npm scripts. A setup shell script is also provided, along with scripts for configuring MCP settings, checking API keys, testing the Docker setup, updating the system, and fixing permissions.

Create a Telegram bot through @BotFather and obtain the numeric user ID from @userinfobot. Configure TELEGRAM_BOT_TOKEN and AUTHORIZED_CHAT_ID in the environment. Select one AI provider by setting either OPENROUTER_API_KEY or OPENAI_API_KEY. The documented Claude configuration starts the MCP process inside the tsgram-mcp-workspace Docker container with tsx and the project’s MCP server entry point.

Tools and capabilities

• Answer questions about the local codebase through Telegram.
• Read selected files and list directory contents with supported helper commands.
• Enable or disable file editing explicitly from the bot chat.
• Pause and resume bot responses.
• Create, test, and monitor Telegram bots from the local dashboard.
• View activity logs and service health information.
• Use Claude 3.5 Sonnet through OpenRouter or GPT-4 through OpenAI, subject to the configured provider.

Limitations and notes

The system is local rather than hosted. Its services, bots, and dashboard depend on the computer remaining online. The project includes safeguards intended to prevent listing, previewing, or serving .env files, but the documentation still advises against using it for highly sensitive material because third-party servers are involved in the transport layer.

Editing is an opt-in operation and should be treated cautiously. The authorized-chat restriction uses a Telegram user ID rather than a username, since usernames can change. The provided material does not document support for Cursor, Windsurf, or Cline, and it does not provide a standalone package-manager installation command for the MCP server.