telegram-mcp 0.2.1

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 to the user via Telegram.

# Status update
interact(message="Working on it...")

# Ask a question (blocks until user replies)
result = interact(message="What's next?", wait_for_reply=True)
print(result["reply"])

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

send_media

Send photos, videos, audio, or documents.

# Send a photo
send_media(media_type="photo", url="https://example.com/image.jpg", caption="Look!")

# Send a document
send_media(media_type="document", url="https://example.com/report.pdf")

# Types: "photo", "video", "audio", "document"

get_file_url

Get download URL for a file from its Telegram file_id.

# When user sends you a file, you get a file_id
result = get_file_url(file_id="AgACAgIAAxk...")
print(result["url"])  # Download URL

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