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

     

     npm run build

     node build/get-chat-id.js

     

     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