# Telegram MCP Server

> Model Context Protocol server for Telegram. Let AI read, search, send, and forward your Telegram messages.

## Quick Start

```bash
# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Telegram API credentials

# Authenticate (first time only)
npm run auth

# Build and run
npm run build
npm start
```

## What It Does

This MCP server exposes Telegram as a set of tools that any MCP-compatible AI client can use:

| Tool | Description |
|------|-------------|
| `telegram_list_chats` | List all your conversations, groups, and channels |
| `telegram_get_me` | Get info about the authenticated account |
| `telegram_read_messages` | Read message history from any chat |
| `telegram_search_messages` | Search messages across all chats |
| `telegram_send_message` | Send a message to any chat |
| `telegram_forward_message` | Forward a message between chats |

## Prerequisites

- **Node.js 18+**
- **Telegram API credentials** — Get them at [my.telegram.org](https://my.telegram.org):
  1. Log in with your phone number
  2. Go to **API Development Tools**
  3. Create an application
  4. Copy `api_id` and `api_hash`

## Configuration

Edit `.env` with your credentials:

```env
API_ID=12345678
API_HASH=your_api_hash_here
SESSION_STRING=
```

> **Note:** `SESSION_STRING` is generated automatically when you run `npm run auth`.

## Authentication

First-time setup requires interactive login:

```bash
npm run auth
```

You'll be prompted for:
1. Phone number (with country code, e.g. `+628123456789`)
2. Auth code (sent to your Telegram app)
3. 2FA password (if enabled)

On success, your session is saved to `.env` automatically.

## Running

### Production

```bash
npm run build
npm start
```

### Development (with hot reload)

```bash
npm run dev
```

## Tool Reference

### `telegram_list_chats`

List all chats (conversations, groups, channels).

```
Parameters:
  limit (number, optional, default: 100)
    Maximum number of chats to return
```

### `telegram_get_me`

Get current authenticated user info. No parameters required.

**Returns:** `id`, `firstName`, `lastName`, `username`, `phone`

### `telegram_read_messages`

Read messages from a specific chat.

```
Parameters:
  chat_id (string, required)
    Chat ID or username (e.g., "@channel", "123456789")

  limit (number, optional, default: 20)
    Number of messages to fetch

  offset_id (number, optional)
    Message ID to start from (for pagination)
```

### `telegram_search_messages`

Search messages across all your Telegram chats.

```
Parameters:
  query (string, required)
    Search query

  limit (number, optional, default: 20)
    Maximum number of results
```

### `telegram_send_message`

Send a message to any chat.

```
Parameters:
  chat_id (string, required)
    Chat ID or username

  text (string, required)
    Message text to send
```

### `telegram_forward_message`

Forward a message from one chat to another.

```
Parameters:
  to_chat_id (string, required)
    Target chat ID or username

  from_chat_id (string, required)
    Source chat ID or username

  message_id (number, required)
    Message ID to forward
```

## Example: Connect to Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["path/to/telegram-mcp/dist/index.js"]
    }
  }
}
```

## Project Structure

```
telegram-mcp/
├── src/
│   ├── index.ts              # MCP server entry (stdio transport)
│   ├── auth.ts               # First-time authentication helper
│   ├── telegram-client.ts    # Telegram client wrapper
│   └── tools/
│       ├── index.ts          # Tool registry
│       ├── list.ts           # list_chats, get_me
│       ├── read.ts           # read_messages, search_messages
│       └── send.ts           # send_message, forward_message
├── .env.example              # Environment template
├── package.json
└── tsconfig.json
```

## Tech Stack

| Package | Purpose |
|---------|---------|
| `@modelcontextprotocol/sdk` | MCP protocol implementation |
| `telegram` | Telegram client (MTProto) |
| `zod` | Input validation |
| `dotenv` | Environment configuration |

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -m 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request

## License

MIT