Telegram

You can run a Telegram MCP Server to access Telegram content through a configurable MCP endpoint. It offers an API mode for direct MTProto access and a web-scraping mode for browser-based retrieval, enabling you to query channels, retrieve complete message metadata, and persist sessions for seamless reuse.

How to use

Set up the Telegram MCP Server as a local service that you connect to from an MCP client. You have two operating modes: API mode (recommended) for fast, authenticated access to Telegram data, and web scraping mode for browser-based retrieval without API credentials. Use the API mode to search channels, access private channels you belong to, and retrieve full message metadata and persistent sessions. Use web scraping mode when you want a quick, credential-free setup or to extract visual media from pages.

How to install

Prerequisites you need before installing are Node.js 18.0.0 or higher and Chrome/Chromium for web scraping. If you plan to use API mode, obtain Telegram API credentials.

Follow these concrete steps to install and configure the server locally.

# Prerequisites check
node -v
chrome --version

# 1) Clone the MCP server project and enter the directory
git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server

# 2) Install dependencies
npm install

# 3) Install Example env file
cp .env.example .env

# 4) Configure environment for API mode (mandatory for API mode; web scraping requires no changes)
# Open the .env file and add your Telegram API credentials
# TELEGRAM_API_ID=your_api_id
# TELEGRAM_API_HASH=your_api_hash

# 5) Build the project
npm run build

# 6) Start the server (example using node directly from the built dist folder)
node dist/index.js

Configuration and usage notes

Telegram API credentials are obtained from Telegram’s developer tools. Set TELEGRAM_API_ID and TELEGRAM_API_HASH in the environment or in the .env file to enable API mode. If you prefer web scraping, you can run without API credentials, and the server will operate in web scraping mode.

{
  "mcpServers": {
    "telegram_scraper": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp-server/dist/index.js"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Security and data handling

Never commit your sensitive configuration files. API credentials are personal and should be kept secure. Session data and cookies are stored per platform; you can override storage paths with the TELEGRAM_DATA_PATH environment variable.

Troubleshooting

If API mode reports not connected to Telegram API, run the telegram_api_login command first. Use the phone number with country code format. For web scraping, ensure a Chrome binary is installed and adjust timeouts if needed.

Development

Common development commands include running in development mode, building, and watching for changes.

# Run in development mode
npm run dev

# Build the project
npm run build

# Watch for changes
npm run watch

Available tools

telegram_api_login

Authenticate with Telegram API to establish a persistent session for API mode usage.

api_scrape_channel

Scrape channel posts via API mode, with optional max_posts limit to control retrieval.

api_search_channel

Search within a channel for specific keywords or phrases.

scrape_channel

Scrape public Telegram channels using web scraping mode.

telegram_login

Login for restricted content when using web scraping mode.