# telegram-mcp

A Model Context Protocol (MCP) server for interacting with Telegram using mtcute.

## Features

- Send text messages to chats
- Wait for incoming messages in specific chats
- Read messages from chats
- Search messages
- List and get information about dialogs (chats)
- Get recent messages across all chats
- Set and inspect emoji-status IDs for accounts and channels

## Setup

### Installation

#### Option 1: Download Pre-built Binary

Download the latest release for your platform from the [releases page](https://github.com/zhigang1992/telegram-mcp/releases):

- **macOS (Apple Silicon)**: `telegram-mcp-darwin-arm64.tar.gz`
- **macOS (Intel)**: `telegram-mcp-darwin-x64.tar.gz`
- **Linux**: `telegram-mcp-linux-x64.tar.gz`
- **Windows**: `telegram-mcp-win-x64.exe.zip`

Extract the archive and make the binary executable (Unix systems):
```bash
tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp
```

#### Option 2: Build from Source

1. Clone the repository and install dependencies:
   ```bash
   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install
   ```

2. Build the executable:
   ```bash
   bun run build
   ```

### Initial Setup (First Time Only)

1. Get your Telegram API credentials from https://my.telegram.org

2. Run the initial setup to authenticate with Telegram:
   ```bash
   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp
   ```
   
   The server will:
   - Prompt you to enter your phone number
   - Send you a verification code via Telegram
   - Ask for the verification code
   - Display the absolute storage path (you'll need this for MCP configuration)

3. Note the storage path displayed in the output. It will look something like:
   ```
   Storage path: /Users/username/telegram-mcp/bot-data/session
   ```

## Usage

### As an MCP Server

Add to your Claude Desktop config using the storage path from the initial setup:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}
```

**Important**: The `TELEGRAM_STORAGE_PATH` must be the absolute path shown during initial setup. This ensures the MCP server uses the authenticated session.

### Available Tools

#### Message Tools

- `messages_sendText` - Send a text message to a chat
  - `chatId` (required): Chat/User ID or username
  - `text` (required): Message text to send
  - `replyToMessageId`: Optional message ID to reply to

- `messages_getHistory` - Get message history from a chat
  - `chatId` (required): Chat/User ID or username
  - `limit`: Number of messages (default: 100, max: 100)
  - `offsetId`: Message ID for pagination

- `messages_search` - Search for messages
  - `query` (required): Search query
  - `chatId`: Specific chat to search in (optional)
  - `limit`: Number of results (default: 50)

- `messages_getRecent` - Get recent messages from all chats
  - `limit`: Number of chats (default: 10)
  - `messagesPerChat`: Messages per chat (default: 10)

#### Interactive Tools

- `wait_for_reply` - Wait for the next message in a chat
  - `chatId` (required): Chat/User ID or username to wait for a message from
  - `timeoutSeconds`: Timeout in seconds (default: 60, max: 300)

#### Status Tools

- `status_getCurrent` - Get the current emoji status for a peer
  - `peerId`: Target peer, defaults to `self`

- `status_setEmoji` - Set or clear an emoji status
  - `peerId`: Target peer, defaults to `self`
  - `emojiId`: Custom emoji document ID, required unless `clear=true`
  - `isCollectible`: Set `true` when `emojiId` is a collectible ID
  - `until`: Optional ISO-8601 timestamp or Unix timestamp string
  - `clear`: Clear the current status instead of setting one

- `status_listAvailable` - List available default emoji-status IDs
  - `scope`: `self` or `channel` (default: `self`)
  - `limit`: Maximum IDs to return (default: 100)

- `status_listCollectibles` - List owned collectible IDs usable as self emoji statuses
  - `owner`: Peer to inspect, defaults to `self`
  - `limit`: Maximum collectibles to return (default: 100)

#### Dialog Tools

- `dialogs_list` - List all dialogs
  - `limit`: Maximum dialogs (default: 50)
  - `filter`: Filter options (onlyUsers, onlyGroups, onlyChannels)

- `dialogs_getInfo` - Get detailed dialog information
  - `chatId` (required): Chat/User ID or username

## Development

Run in development mode:
```bash
bun run dev
```

The server stores session data in `bot-data/` directory.