# Telegram Bot MCP Server

An MCP server to interact with the Telegram Bot API.

## 📦 Installation & Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/mattleads/telegramBotMcp.git
   cd telegramBotMcp
   ```
2. **Install dependencies:**
   ```bash
   npm run build
   ```

## 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:**
   ```bash
   mkdir -p .claude/skills/
   ```
2. **Link the skill folder:**
   ```bash
   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:
   ```bash
   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](https://t.me/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](https://t.me/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:

```json
{
  "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
```bash
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:

```json
{
  "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:

```bash
# 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:
```json
{
  "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:
```json
{
  "mcpServers": {
    "telegram-bot": {
      "url": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}
```