# Telegram MCP

> Full Telegram integration via MCP server using mcporter. Use when the user needs to: (1) Read/send Telegram messages, (2) Manage groups, channels, contacts, (3) Search chats or messages, (4) Create polls, react to messages, (5) Handle invites and subscriptions, (6) Manage profile or privacy settings. Triggers on 'telegram', 'tg chat', 'tg message', 'telegram group', 'send telegram', 'telegram contacts'.

- Skill: `6kmfi6hp/telegram-mcp` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 6kmfi6hp/telegram-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/6kmfi6hp/telegram-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: 6Kmfi6HP (https://skillmd.com/u/6kmfi6hp)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/6kmfi6hp/telegram-mcp

---


# Telegram MCP Skill

Control Telegram via mcporter and the telegram-mcp server.

## Quick Reference

```bash
# List all available tools
mcporter list telegram-mcp --schema

# Call a tool
mcporter call telegram-mcp.<tool_name> param1=value1 param2=value2
```

## Setup

### 1. Clone and Install

```bash
cd ~/.mcp-servers
git clone https://github.com/6Kmfi6HP/telegram-mcp.git
cd telegram-mcp
uv sync
```

### 2. Get Telegram API Credentials

1. Go to https://my.telegram.org/apps
2. Create an application
3. Note your `api_id` and `api_hash`

### 3. Generate Session String

```bash
cd ~/.mcp-servers/telegram-mcp
uv run session_string_generator.py
```

Follow prompts to authenticate. Save the session string.

### 4. Configure Environment

Create `~/.mcp-servers/telegram-mcp/.env`:

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

### 5. Add to mcporter Config

```bash
mcporter config add telegram-mcp --command "uv --directory ~/.mcp-servers/telegram-mcp run main.py"
```

Or manually edit `~/.config/mcporter/mcporter.json`:

```json
{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": ["--directory", "~/.mcp-servers/telegram-mcp", "run", "main.py"]
    }
  }
}
```

## Common Operations

### List Chats

```bash
mcporter call telegram-mcp.get_chats page=1 page_size=20
mcporter call telegram-mcp.list_chats limit=50
```

### Send Message

```bash
mcporter call telegram-mcp.send_message chat_id=123456789 message="Hello!"
mcporter call telegram-mcp.reply_to_message chat_id=123456789 message_id=42 text="Reply text"
```

### Search

```bash
mcporter call telegram-mcp.search_messages chat_id=123456789 query="keyword" limit=20
mcporter call telegram-mcp.search_public_chats query="news"
```

### Contacts

```bash
mcporter call telegram-mcp.list_contacts
mcporter call telegram-mcp.add_contact phone="+1234567890" first_name="John" last_name="Doe"
```

### Groups & Channels

```bash
mcporter call telegram-mcp.create_group title="My Group" user_ids='[111,222]'
mcporter call telegram-mcp.join_chat_by_link link="https://t.me/+AbCdEfGh"
mcporter call telegram-mcp.subscribe_public_channel channel="@channel_name"
```

### Reactions & Polls

```bash
mcporter call telegram-mcp.send_reaction chat_id=123 message_id=42 emoji="👍"
mcporter call telegram-mcp.create_poll chat_id=123 question="Vote?" options='["Yes","No"]'
```

## All Available Tools

See `references/tools.md` for complete tool list with parameters.

**Categories:**
- Chat & Group Management (20+ tools)
- Messaging (20+ tools)
- Contact Management (12+ tools)
- User & Profile (5 tools)
- Search & Discovery (4 tools)
- Stickers & Bots (3 tools)
- Privacy & Settings (7 tools)
- Drafts (3 tools)

## Input Formats

All `chat_id` and `user_id` parameters accept:
- Integer ID: `123456789` or `-1001234567890`
- String ID: `"123456789"`
- Username: `"@username"` or `"username"`

## Notes

- Session string = full account access. Keep it secure!
- File upload/download tools removed due to MCP limitations
- Use `--output json` for machine-readable results