Metadata-Version: 2.4
Name: telethon-mcp
Version: 1.0.0
Summary: Telegram MCP Server — control Telegram through Claude using Telethon. 46 tools for messaging, chats, contacts, media, admin, and advanced features.
Author-email: Hitesh Gupta <hiteshgupta3012@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/dev-hitesh-gupta/telethon-mcp
Project-URL: Repository, https://github.com/dev-hitesh-gupta/telethon-mcp
Project-URL: Issues, https://github.com/dev-hitesh-gupta/telethon-mcp/issues
Keywords: mcp,model-context-protocol,telegram,telethon,claude,ai-tools,automation,messaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.7.1
Requires-Dist: telethon>=1.39.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: cryptg>=0.4.0
Dynamic: license-file

# telethon-mcp

> Telegram MCP Server — control Telegram through Claude using the Telethon library.

[![PyPI version](https://img.shields.io/pypi/v/telethon-mcp.svg)](https://pypi.org/project/telethon-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)

**46 tools** across messaging, chats, contacts, media, admin, and advanced features — powered by [Telethon](https://github.com/LonamiWebs/Telethon), the full-featured Telegram MTProto client.

## Tools

### Messaging (8)
| Tool | Description |
|------|-------------|
| `send_message` | Send a message to a chat or user |
| `edit_message` | Edit a sent message |
| `delete_message` | Delete a message |
| `forward_message` | Forward a message to another chat |
| `reply_to_message` | Reply to a specific message |
| `get_messages` | Get messages from a chat |
| `search_messages` | Search messages across chats |
| `pin_message` | Pin or unpin a message |

### Chats (8)
| Tool | Description |
|------|-------------|
| `list_chats` | List all chats and groups |
| `get_chat_info` | Get details about a chat |
| `create_group` | Create a new group |
| `create_channel` | Create a new channel |
| `join_chat` | Join a chat via link or username |
| `leave_chat` | Leave a chat |
| `archive_chat` | Archive or unarchive a chat |
| `mute_chat` | Mute or unmute a chat |

### Contacts (6)
| Tool | Description |
|------|-------------|
| `list_contacts` | List all contacts |
| `add_contact` | Add a new contact |
| `delete_contact` | Remove a contact |
| `block_user` | Block a user |
| `unblock_user` | Unblock a user |
| `get_user_info` | Get detailed info about a user |

### Media (6)
| Tool | Description |
|------|-------------|
| `send_photo` | Send a photo |
| `send_document` | Send a file/document |
| `send_voice` | Send a voice message |
| `send_video` | Send a video |
| `download_media` | Download media from a message |
| `get_profile_photo` | Get a user or chat's profile photo |

### Admin (9)
| Tool | Description |
|------|-------------|
| `ban_user` | Ban a user from a group/channel |
| `unban_user` | Unban a user |
| `kick_user` | Kick a user from a group |
| `promote_admin` | Promote a user to admin |
| `demote_admin` | Remove admin rights from a user |
| `set_chat_title` | Change a chat's title |
| `set_chat_photo` | Change a chat's photo |
| `get_participants` | List all members of a group/channel |
| `invite_user` | Invite a user to a group/channel |

### Advanced (9)
| Tool | Description |
|------|-------------|
| `send_reaction` | Add a reaction to a message |
| `create_poll` | Create a poll in a chat |
| `schedule_message` | Schedule a message for later |
| `get_scheduled_messages` | List scheduled messages |
| `delete_scheduled_message` | Delete a scheduled message |
| `set_typing` | Send typing indicator |
| `mark_as_read` | Mark messages as read |
| `get_drafts` | Get saved drafts |
| `save_draft` | Save a message draft |

---

## Setup

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
- Telegram API credentials (free from Telegram)

### Step 1 — Get Telegram API Credentials

1. Go to [my.telegram.org/apps](https://my.telegram.org/apps)
2. Log in with your Telegram phone number
3. Click **"Create new application"**
4. Fill in the form (App title and short name can be anything)
5. Copy your **API ID** (number) and **API Hash** (string)

### Step 2 — Install

```bash
pip install telethon-mcp
# or with uv:
uv add telethon-mcp
```

### Step 3 — Generate Session String

```bash
python -m telethon_mcp.generate_session
# or after install:
generate-session
```

This opens an interactive flow:
1. Enter your API ID and API Hash
2. Enter your phone number (with country code)
3. Enter the OTP sent to your Telegram
4. Enter your 2FA password if enabled
5. Copy the generated **session string**

### Step 4 — Configure

Create a `.env` file in your working directory:

```env
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_STRING=your_session_string
```

### Step 5 — Add to Claude Code

```bash
claude mcp add telegram -- uvx telethon-mcp
```

Or manually in your Claude config (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["telethon-mcp"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}
```

---

## Security

- **Session string** gives full access to your Telegram account — treat it like a password
- Never commit your `.env` file or session string to version control
- Add `.env` to your `.gitignore`
- To revoke access: go to Telegram Settings → Privacy → Active Sessions → terminate the session

---

## Troubleshooting

**"TELEGRAM_SESSION_STRING not set":**
Run `generate-session` and add the output to your `.env`.

**"AuthKeyError" or session invalid:**
Your session expired or was revoked. Run `generate-session` again.

**Flood wait errors:**
Telegram rate-limits heavy usage. The server will wait automatically.

**2FA required during session generation:**
Enter your Two-Step Verification password when prompted.

---

## Requirements

- Python 3.10+
- A Telegram account
- Telegram API credentials (free from [my.telegram.org](https://my.telegram.org/apps))

## License

MIT — [Hitesh Gupta](https://github.com/dev-hitesh-gupta)
