MCP Communicator Telegram

🚀 MCP Communicator (Telegram)

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

🚀 Quick Start

Prerequisites

• Node.js (v14 or higher)
• Telegram bot token (obtained from @BotFather)
• Your Telegram chat ID (obtained using the included tool)

Installation

Global Installation via npm

npm install -g mcp-communicator-telegram

On-demand Usage with npx

npx mcptelegram

Get your Telegram chat ID:

npx mcptelegram-chatid

Alternative Installation Steps

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 and obtain the token.

4. Get your Telegram chat ID using the following command:

npx mcptelegram-chatid

Configuration

Add the server to the MCP settings file:

Add the following content to config/mcp.json:

{
  "telegram": {
    "botToken": "your_bot_token",
    "chatId": "your_chat_id"
  }
}

✨ Features

• Ask questions to users via Telegram.
• Send notifications to users (no response required).
• Send files to users via Telegram.
• Create and send ZIP files of projects (respecting .gitignore rules).
• Asynchronously receive user responses (wait indefinitely for responses).
• Support reply-based message tracking.
• Secure chat ID verification.
• Error handling and logging.

💻 Usage Examples

ask_user

Ask questions via Telegram.

Input Mode

{
  "type": "question",
  "question": "Your question?",
  "messageId": "string" // Optional Telegram message ID for associating answers
}

Example Usage

await useMCP({
  server: 'telegram',
  tool: 'ask_user',
  arguments: {
    question: 'What is your favorite color?',
    messageId: '12345'
  }
});

notify_user

Send notifications via Telegram.

Input Mode

{
  "type": "notification",
  "message": "Your message.",
  "messageId": "string" // Optional Telegram message ID
}

Example Usage

await useMCP({
  server: 'telegram',
  tool: 'notify_user',
  arguments: {
    message: 'The system status has been updated.',
    messageId: '67890'
  }
});

send_file

Send files via Telegram.

Input Mode

{
  "type": "file",
  "filePath": "path/to/file", // Optional file path, default is the current directory
  "message": "Optional message content"
}

Example Usage

• Send a file from the default directory:

await useMCP({
  server: 'telegram',
  tool: 'send_file',
  arguments: {}
});

• Send a file from a specific path:

await useMCP({
  server: 'telegram',
  tool: 'send_file',
  arguments: {
    filePath: '/path/to/your/file'
  }
});

zip_project

Create and send a ZIP file of the project.

Input Mode

{
  "type": "directory",
  "directory": "string" // Optional directory path, default is the current working directory
}

Example Usage

• Use the default directory (current working directory):

await useMCP({
  server: 'telegram',
  tool: 'zip_project',
  arguments: {}
});

• Specify a specific directory:

await useMCP({
  server: 'telegram',
  tool: 'zip_project',
  arguments: {
    directory: '/path/to/specific/directory'
  }
});