telegram-mcp 0.5.0

MCP server for Telegram - lets AI agents communicate with users via Telegram

Telegram MCP

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

Installation

pip install telegram-mcp

Configuration

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

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

Get your chat ID: Message @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.

# 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 from URL
interact(message="Here's the result:", media_type="photo", media_url="https://...")

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

# Send a document
interact(media_type="document", media_path="/path/to/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" (auto-detected from extension if not provided)
• media_url: URL of remote media to send
• media_path: Local file path to upload and send

Response format:

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

result = get_messages(limit=10)

Self-Hosting

If you prefer to run your own server:

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

See the GitHub repo for server setup.

License

MIT