# Telegram Bot MCP Server

An MCP (Model Context Protocol) server for sending and receiving Telegram messages via a bot. It allows AI assistants to interact directly with you through Telegram by sending messages, reading recent messages, and sending photos.

## Features

This MCP server provides the following tools:

- `telegram_send_message`: Send a text message to your configured Telegram chat.
- `telegram_get_messages`: Retrieve recent messages sent to the bot (in-memory cache of up to 100 recent messages).
- `telegram_send_photo`: Send an image file (via local absolute path) to your configured Telegram chat, with an optional caption.

## Prerequisites

You will need a Telegram Bot token and your Chat ID:
1. Create a bot using [@BotFather](https://t.me/botfather) on Telegram and get the **Bot Token**.
2. Start a conversation with your bot.
3. Find your **Chat ID** (you can use bots like `@userinfobot` to find your ID).

## Usage

### Running via npx (Recommended)

You can run this MCP server directly using `npx` without needing to clone the repository. This is the easiest way to integrate it into your MCP clients like Claude Desktop or Cursor.

#### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-bot-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_CHAT_ID": "your_chat_id_here"
      }
    }
  }
}
```

*(Note: If the package isn't published to npm yet, you can use the github repo path or a local absolute path to the build/index.js file instead)*

#### Cursor / Other MCP Clients

1. Go to your MCP configuration settings in the client.
2. Add a new server.
3. Type: `stdio`
4. Command: `npx -y telegram-bot-mcp`
5. Make sure to provide the required environment variables:
   - `TELEGRAM_BOT_TOKEN`
   - `TELEGRAM_CHAT_ID`

### Environment Variables

| Variable | Description | Required |
| --- | --- | --- |
| `TELEGRAM_BOT_TOKEN` | Your Telegram Bot token from @BotFather | Yes |
| `TELEGRAM_CHAT_ID` | Your personal Telegram Chat ID | Yes |
| `HTTPS_PROXY` | Optional proxy URL (e.g. `http://127.0.0.1:7890`) | No |

## Local Development

If you want to clone the repo and run it locally:

```bash
# Clone the repository
git clone https://github.com/yourusername/telegram-bot-mcp.git
cd telegram-bot-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (ensure you have set the env vars)
TELEGRAM_BOT_TOKEN=your_token TELEGRAM_CHAT_ID=your_id npm start
```

## Publishing to npm (npx support)

If you haven't published this package yet, you can do so to enable the `npx` usage globally. To publish:

1. Make sure you are logged in to npm: `npm login`
2. Run `npm publish`

After publishing, anyone can use `npx -y telegram-bot-mcp` to use your MCP server.