@ivanbermejo/telegram-mcp

Telegram MCP server for Claude and other AI assistants. Connects via your personal Telegram account (not a bot) using the official MTProto user API.

4 tools, full user-API access — read messages, send files, search, react, pin, scan groups for action items.

Tools

| Tool | Actions | |---|---| | tg_me | Get your account info | | tg_message | get send edit delete forward search pin react | | tg_chat | list read scan summary | | tg_media | send |

Setup

1. Get Telegram API credentials

Go to my.telegram.org/apps, log in, and create an app. Copy the App api_id and App api_hash.

These are your personal developer credentials — different from a bot token.

2. Authenticate (one-time per machine)

TG_APP_ID=your_app_id TG_API_HASH=your_api_hash npx @ivanbermejo/telegram-mcp auth

Follow the prompts: enter your phone number and the verification code Telegram sends you.

The command saves your session locally and prints the config snippet to paste into Claude.

3. Verify the connection

TG_APP_ID=your_app_id TG_API_HASH=your_api_hash npx @ivanbermejo/telegram-mcp test

You should see: ✓ Connected as Your Name (@username)

4. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@ivanbermejo/telegram-mcp"],
      "env": {
        "TG_APP_ID": "your_app_id",
        "TG_API_HASH": "your_api_hash",
        "TG_SESSION": "paste_session_string_here"
      }
    }
  }
}

Restart Claude Desktop. The Telegram tools will appear.

Optional environment variables

| Variable | Description | |---|---| | TG_SESSION | Session string (from auth command). If omitted, reads from ~/.telegram-mcp/session.json | | TG_SCAN_GROUPS | Comma-separated group names for tg_chat scan (e.g. "groupA,groupB") | | TG_CLIENT_MAP | JSON mapping of group keywords to display names (e.g. {"groupA":"Client A"}) | | TG_ALLOWED_DIRS | Colon-separated directories allowed for tg_media send (default: home directory) |

Usage examples

"Who am I on Telegram?"
"Show my unread chats"
"Send 'hello' to @username"
"Search for 'invoice' in the acme group"
"Summarize the last 24 hours in the dev group"
"React with 👍 to message 123 in @channel"
"Pin message 456 in @groupname"
"Scan my groups for action items from the last 12 hours"

Security

• This connects using your personal Telegram account — treat the session string like a password
• To revoke access at any time: Telegram → Settings → Devices → terminate this session
• File sending is restricted to your home directory by default (TG_ALLOWED_DIRS to extend)
• No credentials are hardcoded — everything comes from environment variables

License

MIT