# 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 [@userinfobot](https://t.me/userinfobot) on Telegram.

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.

```python
# Simple text message
interact(message="Working on it...")

# Wait for reply
result = interact(message="What's next?", wait_for_reply=True)
print(result["reply"])

# Yes/No buttons
result = interact(message="Delete?", choices=["Yes", "No"], wait_for_reply=True)

# Send a photo with caption
interact(message="Here's the result:", media_type="photo", media_url="https://...")

# Send a document
interact(media_type="document", media_url="https://.../report.pdf")
```

**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"
- `media_url`: URL of media to send

### `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
