# Telegram Drive MCP Server

MCP server for AI assistants to interact with Telegram files. Connects directly to Telegram via MTProto using [teleproto](https://docs.teleproto.dev).

## Features

- **File Management** - List, search, upload, download, delete, forward files
- **Message Operations** - Send, edit, search messages
- **Dialog Management** - List, join, leave channels
- **Storage Overview** - Get file counts and sizes per dialog

## Setup

### 1. Get Telegram API Credentials

1. Go to [my.telegram.org](https://my.telegram.org)
2. Login with your phone number
3. Click "API development tools"
4. Create an application (fill app title and short name)
5. Copy your `api_id` and `api_hash`

### 2. Install

```bash
npm install
npm run build
```

### 3. Configure

Create `.env` file:

```env
TG_API_ID=your_api_id
TG_API_HASH=your_api_hash
```

### 4. First Login

```bash
npm run dev
```

On first run, you'll be prompted:
1. Enter your phone number
2. Enter the SMS code you received
3. (If 2FA is enabled) Enter your password

After login, you'll see a session string. Copy it to your `.env`:

```env
TG_SESSION=your_session_string_here
```

### 5. Claude Desktop Integration

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

```json
{
  "mcpServers": {
    "telegram-drive": {
      "command": "node",
      "args": ["C:\\path\\to\\telegram-drive-mcp\\dist\\index.js"],
      "env": {
        "TG_API_ID": "your_api_id",
        "TG_API_HASH": "your_api_hash",
        "TG_SESSION": "your_session_string"
      }
    }
  }
}
```

## Available Tools

### File Operations
| Tool | Description |
|------|-------------|
| `td_list_files` | List files in a dialog |
| `td_search_files` | Search files by name |
| `td_get_file_info` | Get file details |
| `td_upload_file` | Upload local file |
| `td_download_file` | Download to local path |
| `td_delete_file` | Delete a file |
| `td_forward_file` | Forward/copy to another dialog |
| `td_bulk_delete` | Delete multiple files |
| `td_bulk_forward` | Forward multiple files |

### Message Operations
| Tool | Description |
|------|-------------|
| `td_send_message` | Send text message |
| `td_edit_message` | Edit message |
| `td_delete_messages` | Delete messages |
| `td_search_messages` | Search in chat |
| `td_get_message_history` | Get chat history |

### Dialog Management
| Tool | Description |
|------|-------------|
| `td_list_dialogs` | List all chats/channels |
| `td_join_channel` | Join a channel |
| `td_leave_channel` | Leave a channel |

### Storage
| Tool | Description |
|------|-------------|
| `td_storage_overview` | Storage stats per dialog |
| `td_get_media_info` | Media details (duration, resolution) |

## Session Security

The session string gives full access to your Telegram account. Treat it like a password:
- Never commit it to git
- Never share it publicly
- Store it in environment variables or a secret manager

## Requirements

- Node.js >= 18.0.0
- Telegram account with api_id/api_hash

## License

MIT