# Telegram MCP Server for Claude Code

Read and search Telegram channel/group/DM messages directly from Claude Code.

Uses MTProto (user account API) via GramJS, so it can read full message history, not just new messages like Bot API.

## Setup

### 1. Get Telegram API credentials

1. Go to https://my.telegram.org/apps
2. Log in with your phone number
3. Create an application
4. Note down your **API ID** and **API Hash**

### 2. Install and authenticate

```bash
cd telegram-mcp-server
npm install
npm run build

# Generate session (interactive, one-time)
TELEGRAM_API_ID=12345 TELEGRAM_API_HASH=abc123def456 npm run auth
```

This will ask for your phone number, send you a code on Telegram, and output a session string. Save it.

### 3. Add to Claude Code

```bash
claude mcp add telegram-mcp \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abc123def456 \
  -e TELEGRAM_SESSION=your_session_string_here \
  -- node /Users/kamal/Desktop/telegram-mcp-server/build/index.js
```

Or add manually to `~/.claude.json`:

```json
{
  "mcpServers": {
    "telegram-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/kamal/Desktop/telegram-mcp-server/build/index.js"],
      "env": {
        "TELEGRAM_API_ID": "12345",
        "TELEGRAM_API_HASH": "abc123def456",
        "TELEGRAM_SESSION": "your_session_string_here"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `list_chats` | List your chats, channels, groups with IDs and unread counts |
| `read_messages` | Read messages from a specific chat/channel/group |
| `search_messages` | Search messages globally or within a specific chat |
| `get_chat_info` | Get detailed info about a chat/channel/group |
| `send_message` | Send a message to any chat |

## Usage in Claude Code

Once configured, just ask Claude:

- "List my Telegram channels"
- "Read the last 50 messages from @channelname"
- "Search for 'meeting notes' across all my Telegram chats"
- "What are the recent messages in the dev group?"

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TELEGRAM_API_ID` | Yes | From my.telegram.org |
| `TELEGRAM_API_HASH` | Yes | From my.telegram.org |
| `TELEGRAM_SESSION` | Yes | Generated via `npm run auth` |