# telegram-mcp

> MCP Server

This repository provides a Telegram MCP server, enabling interaction with Telegram chats through MCP-compatible hosts like Claude for Desktop, using tools for retrieving chats, messages, and sending messages.

## Overview

- **Category:** Communication
- **Language:** Python
- **Stars:** 1461
- **Forks:** 7
- **Owner:** chigwell
- **GitHub:** https://github.com/chigwell/telegram-mcp
- **Created:** 2025-03-20T14:06:35+00:00
- **Updated:** 2025-03-28T18:02:15+00:00
- **Source:** https://model-context-protocol.com/servers/telegram-mcp-server-chat-integration-api

## Setup

## Setup

1.  Clone the Repository:

    ```bash
    git clone https://github.com/chigwell/telegram-mcp
    cd telegram-mcp
    ```

2.  Create Environment File: Copy and rename `.env.example` to `.env` and fill it with your Telegram credentials obtained from [https://my.telegram.org/apps](https://my.telegram.org/apps):

    ```bash
    cp .env.example .env
    ```

    Your `.env` file should look like:

    ```env
    TELEGRAM_API_ID=your_api_id_here
    TELEGRAM_API_HASH=your_api_hash_here
    TELEGRAM_SESSION_NAME=your_session_name
    ```

3.  Setup Python Environment: Use `uv` to set up the Python environment and install dependencies:

    ```bash
    uv venv
    source .venv/bin/activate
    uv add "mcp[cli]" telethon python-dotenv nest_asyncio
    ```

4.  Run the Server (First-time Auth): The first time you run the server, Telethon will prompt you to enter a Telegram authentication code:

    ```bash
    uv run main.py
    ```

    Authenticate by entering the code sent to your Telegram client; this step is only required once.

5. Integrating with Claude for Desktop:

    *   macOS/Linux: Edit your Claude Desktop configuration:

        ```bash
        nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
        ```

        Add this MCP server configuration:

        ```json
        {
            "mcpServers": {
                "telegram-mcp": {
                    "command": "uv",
                    "args": [
                        "--directory",
                        "/ABSOLUTE_PATH/telegram-mcp",
                        "run",
                        "main.py"
                    ]
                }
            }
        }
        ```

        Ensure you replace `/ABSOLUTE_PATH/telegram-mcp` with your project's absolute path.

    *   Windows: Edit your Claude Desktop configuration:

        ```powershell
        nano $env:AppData\Claude\claude_desktop_config.json
        ```

        Add this MCP server configuration:

        ```json
        {
            "mcpServers": {
                "telegram-mcp": {
                    "command": "uv",
                    "args": [
                        "--directory",
                        "C:\\ABSOLUTE_PATH\\telegram-mcp",
                        "run",
                        "main.py"
                    ]
                }
            }
        }
        ```

        Ensure you replace `C:\ABSOLUTE_PATH\telegram-mcp` with your project's absolute path.

## Tools

## Available Tools

		1. `get_chats` (Retrieve a paginated list of your Telegram chats.)
		2. `get_messages` (Retrieve paginated messages from a specific chat.)
		3. `send_message` (Send a message to a specific chat.)