Telegram MCP Server

An MCP server that enables sending and receiving Telegram messages from MCP (Model Context Protocol) clients such as Gemini Spark and Claude Desktop.

Prerequisites

Node.js is required for operation.

1. Install Node.js:

   • If it is not installed yet, download and install the LTS version from the Node.js official website.

   • After installation is complete, restart Command Prompt or PowerShell and verify that node -v and npm -v work.

2. Create a Telegram Bot:

   • Search for @BotFather in the Telegram app and use the /newbot command to create a new bot.

   • Note down the HTTP API Token displayed after creation (e.g., 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).

Related MCP server: Telegram MCP Server

Setup Steps

1. Navigate to the repository directory and install dependencies:

npm install

2. Configure environment variables:

   • Copy .env.example in the directory to .env.

copy .env.example .env

• Open the .env file and set the TELEGRAM_BOT_TOKEN you noted down.

TELEGRAM_BOT_TOKEN=ここにBotのトークンを貼り付け
TELEGRAM_DEFAULT_CHAT_ID=（任意）デフォルトの宛先チャットID

• If TELEGRAM_DEFAULT_CHAT_ID is specified, messages will automatically be sent to that chat when the chat ID is omitted in tool calls.

3. Run the build: Compile TypeScript to JavaScript.

npm run build

Starting the Server and Registering with MCP Clients

1. Start the Server

To start locally, install dependencies, build, and then start as follows.

npm start

By default, the server starts on port 3000 and the following endpoints are available.

• SSE endpoint: http://localhost:3000/sse

To change the port number, start with the environment variable PORT specified, or add PORT=8080 to the .env file.

2. Register with MCP Clients

For Claude Desktop

Add the SSE server to the configuration file (e.g., AppData\Roaming\Claude\claude_desktop_config.json) as follows.

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

For Clients such as Gemini Spark

In the client's settings screen, select the SSE transport and register by specifying http://localhost:3000/sse as the URL.

Provided Tools

1. telegram_get_me

• Overview: Retrieves the bot's own account information. Useful for connection verification tests.

• Parameters: None

2. telegram_send_message

• Overview: Sends a message to the specified chat_id.

• Parameters:

  • text (string, required): The message to send.

  • chat_id (string, optional): The destination chat ID or username (e.g., @my_channel). If not specified, the default ID in .env is used.

  • parse_mode (string, optional): Formatting mode (choose from Markdown, HTML, MarkdownV2).

3. telegram_get_updates

• Overview: Retrieves the latest messages (updates) sent to the bot.

• Parameters:

  • offset (number, optional): The update ID that serves as the starting position for retrieval.

  • limit (number, optional): The maximum number of items to retrieve at once (1-100, default 100).

  • timeout (number, optional): The long polling timeout in seconds.