Telegram Bot MCP Server

An MCP server to interact with the Telegram Bot API.

📦 Installation & Setup

1. Clone the repository:

   git clone https://github.com/mattleads/telegramBotMcp.git
   cd telegramBotMcp

2. Install dependencies:

   npm run build

Related MCP server: agent-telegram-mcp

Tools

• telegram_getMe: Get bot info.

• telegram_sendMessage: Send text messages.

• telegram_sendPhoto: Send photos.

• telegram_sendDocument: Send documents.

Skills

This project includes specialized Skills to help AI agents use this MCP server more effectively.

Usage in Claude Code

1. Create the skills directory:

   mkdir -p .claude/skills/

2. Link the skill folder:

   ln -s "$(pwd)/skills/telegram-notifications" .claude/skills/telegram-notifications

   Note: Claude Code automatically discovers skills in the .claude/skills/ directory of your project.

3. Verify: Restart your Claude Code session and run /telegram-notifications or look for it in the available skills list.

Usage in Gemini CLI

1. Link the skill: From the project root, run:

   gemini skills link skills/telegram-notifications --scope workspace

2. Reload skills: In your interactive Gemini CLI session, run /skills reload.

3. Verify: Run /skills list.

Available Skills

• telegram-notifications: Provides guidance, examples, and common chat IDs for sending notifications.

Telegram Bot & Channel Setup

To use this server, you need a Telegram Bot and a target chat (channel or group).

1. Get a Bot Token

1. Open Telegram and search for @BotFather.

2. Send /newbot and follow the instructions to name your bot.

3. BotFather will provide an API Token. Keep this secure; you will need it for the TELEGRAM_BOT_TOKEN environment variable.

2. Create a Channel & Invite the Bot

1. In Telegram, create a New Channel (or Group).

2. Add your bot as an Administrator.

   • Go to Channel Info -> Administrators -> Add Administrator.

   • Search for your bot's username and add it.

   • Ensure it has the "Post Messages" permission.

3. Find the Chat ID

To send notifications, you need the numeric chat_id.

• Option A: Use the telegram_getChat tool provided by this server with your channel's @username.

• Option B: Forward a message from your channel to @userinfobot or similar bots to get the ID.

• Note: Channel IDs usually start with -100.

Usage with Claude Desktop (Local)

To use this MCP server with Claude Desktop, you need to configure the claude_desktop_config.json file.

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following configuration under the mcpServers section:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "node",
      "args": [
        "/path/to/your/telegram-bot-mcp/build/index.js"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_ACTUAL_TELEGRAM_BOT_TOKEN"
      }
    }
  }
}

Note:

• Replace /path/to/your/telegram-bot-mcp/build/index.js with the absolute path to the build/index.js file in this project directory.

• Replace YOUR_ACTUAL_TELEGRAM_BOT_TOKEN with the API token you received from BotFather.

3. Restart Claude Desktop for the changes to take effect.

Docker Usage

You can containerize the MCP server to run it locally or deploy it.

Build the Docker Image

docker build -t telegram-bot-mcp .

Run Locally via Docker (stdio)

You can configure Claude Desktop to run the docker container via stdio. This avoids needing Node.js installed on your host system:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TELEGRAM_BOT_TOKEN=YOUR_ACTUAL_TELEGRAM_BOT_TOKEN",
        "telegram-bot-mcp"
      ]
    }
  }
}

Deployment to GCP (Cloud Run)

By default, MCP uses stdio for local environments. However, GCP Cloud Run requires an HTTP server listening on a specific port. This project automatically detects the PORT environment variable (set by Cloud Run) and switches to an HTTP SSE (Server-Sent Events) transport.

Deploy via Google Cloud CLI

1. Ensure you have the gcloud CLI installed and authenticated.

2. Submit the build and deploy to Cloud Run:

# Set your GCP Project ID
export PROJECT_ID="your-gcp-project-id"

# Build and deploy the container in one step
gcloud run deploy telegram-bot-mcp \
  --source . \
  --project $PROJECT_ID \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="TELEGRAM_BOT_TOKEN=YOUR_ACTUAL_TELEGRAM_BOT_TOKEN"

Note: Cloud Run automatically sets the PORT environment variable (usually to 8080), which tells the server to start the Express SSE server instead of the stdio server.

Connecting an MCP Client to the Cloud Run Deployment

Remote MCP servers deployed via SSE transport require a client that supports SSE (e.g., configuring Claude Desktop with a custom client implementation or another web-based MCP client).

The server exposes two endpoints:

• GET /sse: Establish the Server-Sent Events connection.

• POST /message: Send MCP JSON-RPC messages to the server.

Usage with Gemini Code Assist

Gemini Code Assist supports MCP servers to extend its capabilities within your IDE (VS Code, IntelliJ, etc.).

Local Setup (stdio)

1. Ensure the project is built: npm run build.

2. Open your IDE's Gemini settings/configuration.

3. Add a new MCP server:

   • Type: stdio

   • Command: node

   • Arguments: ["/absolute/path/to/telegram-bot-mcp/build/index.js"]

   • Environment Variables:

     • TELEGRAM_BOT_TOKEN: YOUR_ACTUAL_TELEGRAM_BOT_TOKEN

Remote Setup (Streamable HTTP / SSE)

If you have deployed the server to Cloud Run or another host:

1. Open your IDE's Gemini settings.

2. Add a new MCP server:

   • Type: sse

   • URL: https://your-cloud-run-url.a.run.app/mcp (or /sse if using older client)

Usage with Gemini CLI

You can add this MCP server to your Gemini CLI globally or within a specific project.

Local Setup (stdio)

1. Ensure the project is built: npm run build.

2. Open your Gemini CLI configuration (~/.gemini/settings.json or project-local .gemini/settings.json).

3. Add the server to the mcpServers object:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-bot-mcp/build/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_ACTUAL_TELEGRAM_BOT_TOKEN"
      }
    }
  }
}

Remote Setup (Streamable HTTP / SSE)

If you have deployed the server to Cloud Run or another host:

1. Open your Gemini CLI configuration.

2. Add the server:

{
  "mcpServers": {
    "telegram-bot": {
      "url": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}