telegram-mcp 0.6.3
MCP server for Telegram - lets AI agents communicate with users via Telegram
Requires Python: >=3.10
Keywords: agent, ai, bot, mcp, telegram

# Telegram MCP

MCP server that lets AI agents communicate with users via Telegram.

## Installation

```bash
pip install telegram-mcp
```

## Configuration

Add to your MCP client config (e.g., Antigravity, Claude Desktop):

```json
{
  "telegram": {
    "command": "telegram-mcp",
    "env": {
      "TELEGRAM_CHAT_ID": "your-chat-id"
    }
  }
}
```

**Get your chat ID:** Message [@agent_comm_mcp_bot](https://t.me/agent_comm_mcp_bot) on Telegram and send `/start`.

That's it! No bot token needed - the client connects to our hosted server.

## Tools

### `interact`

Send a message or media to the user via Telegram.

**Required Parameters:**
- `project_name`: Project/repository name (e.g., "my-project") - shown in message header
- `session_name`: Current task/session context (e.g., "Fix login bug") - shown in message header

**Optional Parameters:**
- `message`: Text to send (optional if sending media)
- `wait_for_reply`: Block until user replies (default: False)
- `choices`: Button labels for quick replies
- `media_type`: "photo", "video", "audio", or "document" (auto-detected from extension if not provided)
- `media_url`: URL of remote media to send
- `media_path`: Local file path to upload and send

### Message Format

Messages appear with a header showing context:

```
🤖 my-project • 📋 Fix login bug
────────────────────
Your message content here...

⏳ Waiting for your reply...
```

### Examples

```python
# Simple status update
interact("my-project", "Deploy", "Working on it...")

# Wait for reply and acknowledge
result = interact("my-project", "Code review", "What's next?", wait_for_reply=True)
interact("my-project", "Code review", f"Got it! Working on: {result['reply']}")

# Yes/No buttons with acknowledgement
result = interact("my-project", "Cleanup", "Delete?", choices=["Yes", "No"], wait_for_reply=True)
if result["reply"] == "Yes":
    interact("my-project", "Cleanup", "Deleting now...")

# Send a photo from URL
interact("my-project", "Results", "Here's the result:", media_type="photo", media_url="https://...")

# Send a local file
interact("my-project", "Export", "Generated image:", media_type="photo", media_path="/path/to/image.png")

# IMPORTANT: Always end with wait_for_reply to keep the loop alive!
interact("my-project", "Complete", "Done! What's next?", wait_for_reply=True)
```

### Agent Guidelines

1. **USE TELEGRAM FOR EVERYTHING** - All status updates, questions, results
2. **ALWAYS END WITH `wait_for_reply=True`** - Never just end; keep the conversation alive
3. **ACKNOWLEDGE IMMEDIATELY** - After receiving a reply, send acknowledgement before doing work
4. **USE MEANINGFUL HEADERS** - `project_name` = repo name, `session_name` = current task

**User Reply Requirement**: When responding to `wait_for_reply` messages, users must **swipe the message** in Telegram to reply. This ensures replies go to the correct request, especially when multiple agents are active.

### Response format

```python
# Text reply
{"reply": "user's text message"}

# Media reply (when user sends photo/video/audio/document)
{
    "reply": {
        "text": "caption if any",
        "media": {
            "type": "photo",
            "file_id": "telegram_file_id",
            "url": "https://api.telegram.org/file/..."
        }
    }
}

# No reply (when wait_for_reply=False)
{"reply": None, "message_id": 123}
```

### `get_messages`

Get recent conversation history.

```python
result = get_messages(limit=10)
```

## Self-Hosting

If you prefer to run your own server:

```json
{
  "telegram": {
    "command": "telegram-mcp",
    "env": {
      "TELEGRAM_SERVER_URL": "https://your-server.com",
      "TELEGRAM_CHAT_ID": "your-chat-id"
    }
  }
}
```

See [the GitHub repo](https://github.com/iamkucuk/telegram-mcp-server) for server setup.

## License

MIT