Telegram MCP

Name: Telegram MCP
Author: chigwell

chigwell

Get started Repository

Telegram MCP server built on Telethon: read chats, send and edit messages, manage groups, contacts and media.

Setup

Choose your client, copy the config, then fill in any required environment variables.

Add to Cursor Add to VS Code

claude mcp add telegram --env TELEGRAM_API_HASH='<TELEGRAM_API_HASH>' --env TELEGRAM_API_ID='<TELEGRAM_API_ID>' --env TELEGRAM_SESSION_NAME='<TELEGRAM_SESSION_NAME>' -- uv --directory /full/path/to/telegram-mcp run main.py

~/.codex/config.toml

[mcp_servers.telegram]
command = "uv"
args = ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"]
env = { TELEGRAM_API_HASH = "<TELEGRAM_API_HASH>", TELEGRAM_API_ID = "<TELEGRAM_API_ID>", TELEGRAM_SESSION_NAME = "<TELEGRAM_SESSION_NAME>" }

# codex mcp add telegram --env TELEGRAM_API_HASH='<TELEGRAM_API_HASH>' --env TELEGRAM_API_ID='<TELEGRAM_API_ID>' --env TELEGRAM_SESSION_NAME='<TELEGRAM_SESSION_NAME>' -- uv --directory /full/path/to/telegram-mcp run main.py

~/.cursor/mcp.json

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_SESSION_NAME": "<TELEGRAM_SESSION_NAME>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_SESSION_NAME": "<TELEGRAM_SESSION_NAME>"
      }
    }
  }
}

~/.gemini/settings.json

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_SESSION_NAME": "<TELEGRAM_SESSION_NAME>"
      }
    }
  }
}

claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_SESSION_NAME": "<TELEGRAM_SESSION_NAME>"
      }
    }
  }
}

.trae/mcp.json

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_SESSION_NAME": "<TELEGRAM_SESSION_NAME>"
      }
    }
  }
}

Environment variables

TELEGRAM_API_HASH
TELEGRAM_API_ID
TELEGRAM_SESSION_NAME

Replace the placeholders with your own credentials and keep them out of version control.

Setup

Environment variables

Related