Telegram MCP server

Telegram MCP Server provides a powerful bridge between Claude and Telegram content through the Model Context Protocol. It offers two operation modes: a fast API mode using Telegram's MTProto protocol and a browser-based web scraping mode, allowing Claude to fetch and analyze Telegram channel content effectively.

Prerequisites

• Node.js 18.0.0 or higher
• Chrome/Chromium (for web scraping mode)
• Telegram API credentials (for API mode) from my.telegram.org

Installation

Step 1: Clone the repository

git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server

Step 2: Install dependencies

npm install

Step 3: Set up configuration

cp .env.example .env

Edit the .env file to add your configuration:

• For API mode: Add your TELEGRAM_API_ID and TELEGRAM_API_HASH
• For web scraping: Default settings work out of the box

Step 4: Build the project

npm run build

Configuration

Getting Telegram API Credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Click "API development tools"
4. Create a new application
5. Copy your api_id and api_hash to the .env file

Claude Desktop Configuration

Add this to your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

Usage

After configuration, restart Claude Desktop. The Telegram tools will be available in Claude.

API Mode Tools

Authenticate with Telegram

This is only needed the first time:

Use telegram_api_login to connect to Telegram

Scrape channel posts

By default, this retrieves all available posts:

Use api_scrape_channel with url="https://t.me/channelname"

With a limit:

Use api_scrape_channel with url="https://t.me/channelname" and max_posts=50

Search within a channel

Use api_search_channel with url="https://t.me/channelname" and query="keyword"

Web Scraping Tools

Scrape public channels

Use scrape_channel with url="https://t.me/channelname"

Login for restricted content

Use telegram_login with phone="+1234567890"

Data Storage

Session data and cookies are stored in platform-specific directories:

• Windows: %APPDATA%\telegram-mcp-data
• macOS: ~/Library/Application Support/telegram-mcp-data
• Linux: ~/.config/telegram-mcp-data

You can override this with the TELEGRAM_DATA_PATH environment variable.

Troubleshooting

API Mode Issues

• "Not connected to Telegram API": Run telegram_api_login first
• Phone number format: Include country code (e.g., +1234567890)
• 2FA errors: Enter your 2FA password when prompted

Web Scraping Issues

• "No Chrome binary found": Install Chrome or Chromium
• Login issues: Ensure you're using the correct phone format
• Timeout errors: Increase BROWSER_TIMEOUT in .env

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect