📌Overview

Purpose: To facilitate user communication via Telegram through an MCP server and bot interface.

Overview: MCP Communicator (Telegram) is designed to enable seamless interactions between server applications and users through a dedicated Telegram bot. The framework allows for functionalities such as querying users, sending notifications, sharing files, and archiving project directories.

Key Features:

Ask Questions: Allows the server to ask questions and receive user responses asynchronously.
Send Notifications: Enables sending one-way messages to users without expecting a reply.
File Sharing: Supports sending various files directly through Telegram for convenient access.
Project Zipping: Creates zip files of projects while respecting .gitignore patterns and sends them to users.
Secure Interaction: Validates chat IDs to ensure secure communication and tracks message context for reliable interactions.

MCP Communicator (Telegram)

An MCP server that enables communication with users through Telegram. This server provides tools to interact with users via a Telegram bot, including asking questions, sending notifications, sharing files, and creating project archives.

Installation

Global Installation via npm

npm install -g mcp-communicator-telegram

On-Demand Installation via npx

npx mcptelegram

To get your Telegram chat ID:

npx mcptelegram-chatid

Features

Ask questions to users through Telegram.
Send notifications to users (no response required).
Send files to users via Telegram.
Create and send project zip files (respecting .gitignore).
Receive responses asynchronously.
Support for reply-based message tracking.
Secure chat ID validation.
Error handling and logging.

Prerequisites

Node.js (v14 or higher)
A Telegram bot token (obtained from @BotFather)
Your Telegram chat ID (can be obtained using the included utility)

Configuration

Add the server to your MCP settings file:

{
  "mcpServers": {
    "mcp-communicator-telegram": {
      "command": "node",
      "args": ["path/to/mcp-communicator-telegram/build/index.js"],
      "env": {
        "TELEGRAM_TOKEN": "your_bot_token_here",
        "CHAT_ID": "your_chat_id_here"
      }
    }
  }
}

Available Tools

ask_user

Asks a question to the user via Telegram and waits for their response.

Input Schema:

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The question to ask the user"
    }
  },
  "required": ["question"]
}

Example Usage:

const response = await use_mcp_tool({
  server_name: "mcp-communicator-telegram",
  tool_name: "ask_user",
  arguments: {
    question: "What is your favorite color?"
  }
});

notify_user

Sends a notification message to the user via Telegram.

Input Schema:

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The message to send to the user"
    }
  },
  "required": ["message"]
}

Example Usage:

await use_mcp_tool({
  server_name: "mcp-communicator-telegram",
  tool_name: "notify_user",
  arguments: {
    message: "Task completed successfully!"
  }
});

send_file

Sends a file to the user via Telegram.

Input Schema:

{
  "type": "object",
  "properties": {
    "filePath": {
      "type": "string",
      "description": "The path to the file to send"
    }
  },
  "required": ["filePath"]
}

Example Usage:

await use_mcp_tool({
  server_name: "mcp-communicator-telegram",
  tool_name: "send_file",
  arguments: {
    filePath: "path/to/file.txt"
  }
});

zip_project

Creates a zip file of a project directory and sends it to the user via Telegram.

Input Schema:

{
  "type": "object",
  "properties": {
    "directory": {
      "type": "string",
      "description": "Directory to zip"
    }
  },
  "required": []
}

Example Usage:

await use_mcp_tool({
  server_name: "mcp-communicator-telegram",
  tool_name: "zip_project",
  arguments: {}
});

Development

Build the project:

npm run build

Run in development mode:

npm run dev

Security

The server only responds to messages from the configured chat ID.
Environment variables are used for sensitive configuration.
The bot ignores messages without proper context.

License

ISC

Author

qpd-v

Version

0.2.1