Telegram Bot MCP Server

An MCP (Model Context Protocol) server for sending and receiving Telegram messages via a bot. It allows AI assistants to interact directly with you through Telegram by sending messages, reading recent messages, and sending photos.

Features

This MCP server provides the following tools:

• telegram_send_message: Send a text message to your configured Telegram chat.
• telegram_get_messages: Retrieve recent messages sent to the bot (in-memory cache of up to 100 recent messages).
• telegram_send_photo: Send an image file (via local absolute path) to your configured Telegram chat, with an optional caption.

Prerequisites

You will need a Telegram Bot token and your Chat ID:

1. Create a bot using @BotFather on Telegram and get the Bot Token.
2. Start a conversation with your bot.
3. Find your Chat ID (you can use bots like @userinfobot to find your ID).

Usage

Running via npx (Recommended)

You can run this MCP server directly using npx without needing to clone the repository. This is the easiest way to integrate it into your MCP clients like Claude Desktop or Cursor.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-bot-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_CHAT_ID": "your_chat_id_here"
      }
    }
  }
}

(Note: If the package isn't published to npm yet, you can use the github repo path or a local absolute path to the build/index.js file instead)

Cursor / Other MCP Clients

1. Go to your MCP configuration settings in the client.
2. Add a new server.
3. Type: stdio
4. Command: npx -y telegram-bot-mcp
5. Make sure to provide the required environment variables:
   • TELEGRAM_BOT_TOKEN
   • TELEGRAM_CHAT_ID

Environment Variables

Variable	Description	Required
TELEGRAM_BOT_TOKEN	Your Telegram Bot token from @BotFather	Yes
TELEGRAM_CHAT_ID	Your personal Telegram Chat ID	Yes
HTTPS_PROXY	Optional proxy URL (e.g. http://127.0.0.1:7890)	No

Local Development

If you want to clone the repo and run it locally:

# Clone the repository
git clone https://github.com/yourusername/telegram-bot-mcp.git
cd telegram-bot-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (ensure you have set the env vars)
TELEGRAM_BOT_TOKEN=your_token TELEGRAM_CHAT_ID=your_id npm start

Publishing to npm (npx support)

If you haven't published this package yet, you can do so to enable the npx usage globally. To publish:

1. Make sure you are logged in to npm: npm login
2. Run npm publish

After publishing, anyone can use npx -y telegram-bot-mcp to use your MCP server.