# Telegram Notifier MCP Server

A Model Context Protocol (MCP) server that provides a tool to send notifications via Telegram. Built with TypeScript and Node.js.

## Features

- **Single Tool**: `send_telegram_notification` - Send messages to a configured Telegram chat
- **Simple Setup**: Configure once with environment variables
- **Error Handling**: Clear error messages for configuration and API issues
- **TypeScript**: Fully typed for better development experience

## Prerequisites

1. **Node.js**: Version 18 or higher
2. **Telegram Bot Token**: Create a bot via [@BotFather](https://t.me/botfather) on Telegram
3. **Chat ID**: Get your chat ID (you can use [@userinfobot](https://t.me/userinfobot))

## Installation

```bash
# Install dependencies
npm install

# Build the TypeScript code
npm run build
```

## Configuration

### Environment Variables

Set the following environment variables:

```bash
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
```

You can also create a `.env` file in your project root:

```env
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cline):

#### For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": ["/Users/yarden.porat/projects/yarden/telegram-notifier-mcp/dist/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_CHAT_ID": "your_chat_id_here"
      }
    }
  }
}
```

#### For Cline (VS Code extension):

Add to your Cline MCP settings:

```json
{
  "telegram-notifier": {
    "command": "node",
    "args": ["/Users/yarden.porat/projects/yarden/telegram-notifier-mcp/dist/index.js"],
    "env": {
      "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
      "TELEGRAM_CHAT_ID": "your_chat_id_here"
    }
  }
}
```

## Usage

Once configured, the MCP server provides a single tool:

### `send_telegram_notification`

**Parameters:**
- `message` (string, required): The message text to send to Telegram

**Example:**
```
Send a telegram notification with the message "Deployment completed successfully! 🚀"
```

The AI assistant will use the tool to send your message to the configured Telegram chat.

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

### Testing

You can test the server manually by setting environment variables and running:

```bash
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"
node dist/index.js
```

Or use the included shell script:

```bash
./send_telegrem_notification.sh "Test message"
```

## Project Structure

```
telegram-notifier-mcp/
├── src/
│   └── index.ts              # Main server implementation
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # Node.js dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                 # This file
└── send_telegrem_notification.sh  # Shell script for testing
```

## How to Get Telegram Credentials

### 1. Create a Telegram Bot

1. Open Telegram and search for [@BotFather](https://t.me/botfather)
2. Send `/newbot` command
3. Follow the instructions to name your bot
4. Copy the bot token provided (format: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)

### 2. Get Your Chat ID

**Option 1: Using @userinfobot**
1. Search for [@userinfobot](https://t.me/userinfobot) on Telegram
2. Start a chat with it
3. Your chat ID will be displayed

**Option 2: Using your bot**
1. Start a chat with your newly created bot
2. Send any message to it
3. Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
4. Look for `"chat":{"id":` in the response

## Troubleshooting

### Bot not sending messages

- Ensure you've started a chat with your bot (send `/start`)
- Verify your bot token is correct
- Check that the chat ID is correct

### MCP server not connecting

- Make sure the path to `dist/index.js` is absolute and correct
- Verify Node.js is installed and accessible
- Check that the build completed successfully (`npm run build`)

## License

MIT