What is Mcp Communicator Telegram

mcp-communicator-telegram is an MCP server that facilitates communication with users through Telegram. It allows interaction via a Telegram bot, enabling functionalities such as asking questions, sending notifications, sharing files, and creating project archives.

Use cases

Use cases for mcp-communicator-telegram include project management where team members can be queried for updates, sending notifications about task completions, sharing project files, and archiving project directories for easier distribution.

How to use

To use mcp-communicator-telegram, install it via npm or npx. Set up your Telegram bot using @BotFather to obtain a bot token, and retrieve your Telegram chat ID using the provided utility. Configure the server in your MCP settings file with the necessary environment variables.

Key features

Key features include the ability to ask questions to users, send notifications, share files, create project zip files while respecting .gitignore, receive asynchronous responses, and secure chat ID validation.

Where to use

undefined

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

Via npm (global)

npm install -g mcp-communicator-telegram

Via npx (on-demand)

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 (waits indefinitely for response)
• 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)

Installation

1. Clone the repository:

git clone https://github.com/qpd-v/mcp-communicator-telegram.git
cd mcp-communicator-telegram

2. Install dependencies:

npm install

3. Create a Telegram bot:

   • Open Telegram and search for @BotFather
   • Send /newbot and follow the instructions
   • Save the bot token you receive

4. Get your chat ID:

   • Copy .env.example to .env
   • Add your bot token to the .env file:

     TELEGRAM_TOKEN=your_bot_token_here
     

   • Run the chat ID utility:

     npm run build
     node build/get-chat-id.js
     

   • Send any message to your bot
   • Copy the chat ID that appears in the console
   • Add the chat ID to your .env file:

     TELEGRAM_TOKEN=your_bot_token_here
     CHAT_ID=your_chat_id_here
     

Configuration

Add the server to your MCP settings file (usually located at %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json on Windows):

{
  "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 (no response required).

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 (respecting .gitignore patterns) and sends it to the user via Telegram.

Input Schema:

{
  "type": "object",
  "properties": {
    "directory": {
      "type": "string",
      "description": "Directory to zip (defaults to current working directory)"
    }
  },
  "required": []
}

Example usage with default directory (current working directory):

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

Example usage with specific directory:

await use_mcp_tool({
  server_name: "mcp-communicator-telegram",
  tool_name: "zip_project",
  arguments: {
    directory: "/path/to/your/project"
  }
});

Features:

• Creates a zip file named [project-name]-project.zip based on the directory name
• Can zip any specified directory or the current working directory
• Respects .gitignore patterns
• Maintains correct file paths in the archive
• Automatically cleans up the zip file after sending
• Handles files up to 2GB in size

Development

Build the project:

npm run build

Run in development mode:

npm run dev

Watch for changes:

npm run watch

Clean build directory:

npm run clean

Security

• The server only responds to messages from the configured chat ID
• Environment variables are used for sensitive configuration
• Message IDs are used to track question/answer pairs
• The bot ignores messages without proper context

License

ISC

Author

qpd-v

Version

0.2.1 # Major version bump for new features: notify_user, send_file, and zip_project tools