telegram

This MCP server acts as a bridge between the Telegram API and AI assistants by exposing Telegram-related tools that an AI can call through the MCP interface. It provides capabilities to get account information, list dialogs (with optional unread filtering), mark dialogs as read, retrieve messages from a specific dialog, and send draft messages to dialogs. These tools enable AI agents to interact with a user’s Telegram data in a controlled, context-aware way, while keeping user consent and API terms in mind.

To use the server, run it with the preferred launcher (for example using NPX as shown in the configuration). Once running, configure your client (for example Claude Desktop or Cursor) to connect to the Telegram MCP server by specifying the server name and the command to start it, along with the necessary Telegram API credentials. In your client’s MCP configuration, you will typically reference the server as a local tool, providing TG_APP_ID and TG_API_HASH as environment variables. After configuration, the AI can issue prompts that invoke tools like tg_me, tg_dialogs, tg_read, tg_dialog, and tg_send to interact with Telegram data.

Prerequisites:

• Node.js and npm (to use NPX) or just NPX installed
• Optional: Go if you prefer building from source (not required for NPX method)

Recommended installation via NPX (fastest for most users):

1. Ensure you have NPX available (comes with npm):
   • npm install -g npm
2. Run the server directly via NPX when needed:
   • npx -y @chaindead/telegram-mcp

Alternative: Install from releases (prebuilt binaries) and run locally:

1. Download the latest release for your OS from the project releases page.
2. Extract and place the binary in a directory in your PATH.
3. Run the binary (the exact command will depend on the binary name, e.g. telegram-mcp).

From Source (Go required):

1. Install Go 1.24+ and ensure GOBIN is in your PATH.
2. Run: go install github.com/chaindead/telegram-mcp@latest
3. Run the binary from your Go bin directory.

Configuration notes:

• When using NPX, you’ll typically configure your MCP clients with: { "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "@chaindead/telegram-mcp"], "env": { "TG_APP_ID": "<your-api-id>", "TG_API_HASH": "<your-api-hash>" } } } }

Tips and common issues:

• You must obtain a Telegram API ID and hash from my.telegram.org and provide them via TG_APP_ID and TG_API_HASH in your environment configuration.
• Ensure you comply with Telegram's Terms of Service; misuse can lead to account suspension.
• If using NPX, you can still pass additional environment variables or override PATH/HOME in your client configuration as shown in the README instructions.
• When connecting from Claude Desktop or Cursor, ensure the mcpServers entry uses the exact server name (telegram) and that the command points to the correct launcher binary or npm package.
• If you encounter authentication issues, re-run the auth flow described in the configuration section to re-establish the Telegram session.
• For production deployments, consider running behind a secure environment and controlling access to the MCP endpoints to prevent unauthorized tool calls.