tg-mcp

ogk-code/tg-mcp

3.2

If you are the rightful owner of tg-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP server that connects AI assistants to Telegram via MTProto API.

Tools
10
Resources
0
Prompts
0

tg-mcp

MCP server that connects AI assistants to Telegram via MTProto API.

Built with gotd/td and go-sdk.

Features

  • Authentication: Login with phone number and 2FA support
  • Messages: Send and read messages
  • Chats: List dialogs, get chat overview with recent messages
  • Management: Leave channels/groups, delete chats

Available Tools

ToolDescription
auth_statusCheck authorization status
auth_send_codeSend login code to phone
auth_submit_codeSubmit code (with optional 2FA password)
auth_logoutLogout and clear session
list_chatsGet list of dialogs with unread counts
get_chats_overviewGet all chats with recent messages in one request
get_messagesGet messages from a specific chat
send_messageSend a message to a chat
leave_channelLeave a channel or group
delete_chatDelete a chat/dialog

Installation

Prerequisites

  1. Go 1.21+
  2. Telegram API credentials from https://my.telegram.org/apps

Build

git clone https://github.com/yourusername/tg-mcp.git
cd tg-mcp
go build -o tg-mcp .

Cross-compile for Windows:

GOOS=windows GOARCH=amd64 go build -o tg-mcp.exe .

Configuration

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/tg-mcp",
      "args": [],
      "env": {
        "TG_APP_ID": "your_app_id",
        "TG_APP_HASH": "your_app_hash"
      }
    }
  }
}

Windows example:

{
  "mcpServers": {
    "telegram": {
      "command": "C:\\Users\\YourName\\tg-mcp.exe",
      "args": [],
      "env": {
        "TG_APP_ID": "your_app_id",
        "TG_APP_HASH": "your_app_hash"
      }
    }
  }
}

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": "/path/to/tg-mcp",
      "env": {
        "TG_APP_ID": "your_app_id",
        "TG_APP_HASH": "your_app_hash"
      }
    }
  }
}

Open WebUI (via mcpo)

Use mcpo to expose as OpenAPI:

pip install mcpo
TG_APP_ID=your_id TG_APP_HASH=your_hash mcpo --port 8000 -- /path/to/tg-mcp

Then add http://localhost:8000 as OpenAPI server in Open WebUI.

Environment Variables

VariableRequiredDescription
TG_APP_IDYesTelegram API ID
TG_APP_HASHYesTelegram API Hash
TG_SESSION_FILENoCustom session file path (default: ~/.tg-mcp-session.json)

Usage

After configuring, restart your MCP client (Claude Desktop, Claude Code, etc.).

First-time Authorization

  1. Use auth_send_code with your phone number
  2. You'll receive a code in Telegram
  3. Use auth_submit_code with the code (and password if 2FA is enabled)
  4. Done! Session is saved for future use

Example Prompts

  • "Show me my recent Telegram chats"
  • "Send a message to @username saying hello"
  • "What are my unread messages?"
  • "Leave the channel @spamchannel"

Security

  • Session file (~/.tg-mcp-session.json) contains your auth key — keep it private!
  • APP_ID/APP_HASH are not sensitive — they identify the app, not your account
  • Uses MTProto (user API), not Bot API — full account access

License

MIT