telegram

This Telegram MCP Server provides tools to interact with the Telegram Bot API through an MCP interface. It exposes utilities to query bot information, send messages to chats, fetch incoming updates via long polling, and forward messages between chats. You can access the following tools: get_bot_info (no parameters; returns a bot User object), send_message (requires chatId and text, with optional params for parse_mode, reply_markup, etc.), get_updates (optional params like offset, limit, timeout, allowed_updates to tailor update retrieval), and forward_message (requires chatId, fromChatId, and messageId with optional parameters such as message_thread_id and disable_notification). These tools enable programmatic bot control, message delivery, and real-time updates integration for your AI assistants or automation workflows.

To use the tools, connect to the MCP server endpoint provided by the running Telegram MCP Server. Use get_bot_info to verify the bot configuration and token, then call send_message to post messages to a chat identified by chatId. Use get_updates to poll for new Telegram updates and process them in your application, and use forward_message to propagate messages between chats or channels as needed. All requests should include the Telegram bot token configured in TELEGRAM_BOT_TOKEN, which is required to authenticate with the Telegram Bot API.

The server is designed to be used in a development or production environment where you want programmatic access to a Telegram bot from an external agent or AI assistant. It encapsulates the Telegram Bot API interactions behind a simple MCP-powered surface, enabling you to integrate bot actions as part of broader automation workflows.

Prerequisites:

• Node.js (recommended LTS) and npm installed on your machine
• Access to the repository containing this MCP server
• A Telegram bot token created via BotFather (you will set TELEGRAM_BOT_TOKEN later)

Installation steps:

1. Clone the repository: git clone https://github.com/your-org/nexusx-mcp-telegram-mcp-server.git cd nexusx-mcp-telegram-mcp-server

2. Install dependencies: npm install

3. Build the project (if applicable): npm run build

4. Prepare environment variable for the bot token. You can set it in your environment or pass it when running the server. Example (UNIX): export TELEGRAM_BOT_TOKEN=your_bot_token

5. Run the MCP server with the inspector (as recommended by the project): npx @modelcontextprotocol/inspector node dist/index.js

6. Confirm the server is running. Open http://127.0.0.1:6274 to set up the environment and interact with the tools.

Notes:

• The server expects TELEGRAM_BOT_TOKEN to be set for authenticating with the Telegram Bot API.
• If you modify environment variables, restart the server to apply changes.

Tips and common issues:

• Ensure the Telegram bot token is correct and active; tokens can be regenerated via BotFather if needed.
• When using get_updates, consider configuring timeout and offset to manage long polling efficiently and avoid duplicate updates.
• For forward_message, be mindful of channel or chat permissions; you may need to add the bot to the target chat with appropriate privileges.
• If you encounter connection issues, verify network access to api.telegram.org and that your host allows outbound HTTPS traffic.
• The Open Telemetry/Inspector integration helps introspect requests; use the provided UI at http://127.0.0.1:6274 to tune environment and tool behavior.