Telegram MCP Bridge

Самый простой вариант установки теперь — Docker Compose: он запускает мост, локальную веб-панель Telegram и официальный OpenAI tunnel-client sidecar.

Установка через Docker Compose

Нужны Docker Desktop, Telegram api_id/api_hash, OpenAI Tunnel ID и Runtime API key.

1. Создайте приложение на https://my.telegram.org и сохраните api_id и api_hash.

2. В OpenAI Platform → Tunnels создайте туннель и скопируйте значение вида tunnel_....

3. В OpenAI Platform → API keys создайте Runtime API key для туннеля. Admin key для запуска не нужен.

4. Скопируйте .env.example в .env и заполните:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash
ADMIN_USERNAME=admin
ADMIN_PASSWORD=use_a_long_random_password
TUNNEL_ID=tunnel_your_id
CONTROL_PLANE_API_KEY=sk-your_runtime_key

5. Запустите сервисы:

docker compose up --build -d
docker compose logs -f

Во время сборки sidecar сам скачивает официальный tunnel-client v0.0.10 для архитектуры Docker (amd64 или arm64) и проверяет SHA-256. В рантайме он читает TUNNEL_ID и CONTROL_PLANE_API_KEY из .env, создаёт профиль и подключает внутренний MCP endpoint http://telegram-bridge:8765/mcp/.

Откройте http://127.0.0.1:8765, введите ADMIN_USERNAME/ADMIN_PASSWORD, затем:

1. укажите номер Telegram в международном формате;

2. введите код, пришедший от Telegram;

3. если включена двухэтапная аутентификация, введите пароль 2FA.

Код подтверждения и пароль 2FA не сохраняются. Telegram-сессия лежит в именованном Docker volume telegram-session, поэтому повторно входить после перезапуска не нужно.

Проверьте состояние:

docker compose ps
curl http://127.0.0.1:8080/readyz

После этого создайте или обновите коннектор в ChatGPT → Настройки → Коннекторы, пока оба контейнера запущены. Внешний URL вручную придумывать не требуется: коннектор связан с созданным Tunnel ID.

Остановка и обновление:

docker compose down
docker compose pull
docker compose up --build -d

Не используйте docker compose down -v, если хотите сохранить Telegram-сессию. Файл .env уже исключён из Git; никогда не коммитьте Runtime API key или session-файлы.

Настройки Docker

Порты публикуются только на 127.0.0.1. Не выставляйте веб-панель напрямую в интернет. Для production предпочтительнее Docker secrets вместо .env.

Диагностика Docker

exec /usr/local/bin/tunnel-entrypoint: no such file or directory

На Windows эта ошибка обычно означает, что shell-скрипт попал в образ с окончаниями строк CRLF, и Linux пытается найти интерпретатор с именем /bin/sh\r. Это не означает, что сам файл действительно отсутствует.

В актуальной версии проекта проблема исправлена двумя уровнями защиты:

• .gitattributes сохраняет все *.sh с окончаниями LF;

• Dockerfile дополнительно удаляет CR при сборке образа.

Получите исправление и полностью пересоберите только tunnel-контейнер:

git pull
docker compose down
docker compose build --no-cache tunnel-client
docker compose up -d
docker compose logs -f tunnel-client

Удалять volumes не требуется: авторизованная Telegram-сессия останется на месте. Не запускайте docker compose down -v, иначе volume с сессией будет удалён.

Проверка состояния

docker compose ps
docker compose logs --tail=100 telegram-bridge
docker compose logs --tail=100 tunnel-client
curl.exe http://127.0.0.1:8765/readyz
curl.exe http://127.0.0.1:8080/readyz

Оба контейнера должны иметь состояние running/healthy. В логах моста ожидаются Application startup complete и StreamableHTTP session manager started. В логах туннеля не должно быть циклического перезапуска или ошибок 401 Unauthorized.

401 Unauthorized от control plane

Проверьте, что CONTROL_PLANE_API_KEY является именно Runtime API key, а не Admin key, и что ключ и TUNNEL_ID созданы в одной OpenAI Platform organization. После изменения .env пересоздайте контейнер:

docker compose up -d --force-recreate tunnel-client
docker compose logs -f tunnel-client

Веб-панель возвращает 401 Unauthorized

Это ожидаемый HTTP Basic challenge. Браузер должен показать окно входа — используйте ADMIN_USERNAME и ADMIN_PASSWORD из .env. Запись GET / 401 перед последующим GET / 200 в логах означает нормальный успешный вход.

A local, read-only MCP bridge for accessing your own Telegram account through a user session. It uses Telethon (MTProto), not the Telegram Bot API.

Related MCP server: telegram-mcp

Current tools

• telegram_list_chats

• telegram_get_messages

• telegram_search_messages

• telegram_get_message_context

• telegram_get_chat_info

• telegram_get_image

The first version cannot send, edit, delete, forward, or mark messages as read.

Requirements

• Python 3.11+

• Poetry

• Telegram api_id and api_hash from https://my.telegram.org

• An OpenAI Platform organization with Secure MCP Tunnel access

• ChatGPT developer mode / custom plugins enabled

• tunnel-client.exe for Windows

Windows installation with Poetry

Clone and install the project:

cd C:\Users\YOUR_USER\Documents\Code
git clone https://github.com/boltholds/Telegram_MCP_Bridge.git
cd Telegram_MCP_Bridge
poetry install

Create the local configuration:

copy .env.example .env
notepad .env

Telegram API credentials

1. Sign in at https://my.telegram.org.

2. Open API development tools.

3. Create an application and copy its api_id and api_hash.

4. Fill in .env:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=replace_me
TELEGRAM_PHONE=+79990000000
TELEGRAM_SESSION_PATH=./sessions/telegram_mcp
TELEGRAM_ALLOWED_CHAT_IDS=
TELEGRAM_MAX_MESSAGES_PER_REQUEST=100
TELEGRAM_MAX_SEARCH_RESULTS=100
TELEGRAM_MAX_MEDIA_BYTES=10485760

Authorize the Telegram user session:

poetry run telegram-mcp-login

Telegram sends the code to an already authorized Telegram client. Enter the 2FA password when requested. A successful login creates sessions/telegram_mcp.session; this file grants access to the account and must never be shared or committed.

Test the stdio MCP server:

poetry run telegram-mcp

The command normally stays silent and waits for MCP requests. Stop it with Ctrl+C.

Connect ChatGPT through Secure MCP Tunnel

ChatGPT cannot invoke a local stdio process directly from a cloud conversation. Secure MCP Tunnel runs next to the bridge and opens an outbound-only HTTPS connection to OpenAI. The Telegram MCP server remains local and does not require an inbound port.

1. Create a tunnel and copy its ID

1. Open OpenAI Platform tunnel settings.

2. Select the same Platform organization used by the target ChatGPT account.

3. Create a tunnel, for example telegram-mcp.

4. Associate it with the target personal ChatGPT workspace (or the required Business/Enterprise workspace).

5. Copy the tunnel ID, which looks like tunnel_....

The account needs Tunnels Read + Use to run and select a tunnel. Creating or editing one additionally requires Tunnels Read + Manage.

2. Create the runtime API key

Create a runtime key at Platform organization API keys. The key and tunnel must belong to the same Platform organization. Do not use an Admin API key and never put the key into the repository or .env.

Set it only in the current cmd.exe window:

set "CONTROL_PLANE_API_KEY=sk-REPLACE_ME"

Verify that the variable exists without printing the secret:

if defined CONTROL_PLANE_API_KEY (echo API key is set) else (echo API key is missing)

The variable disappears when the terminal closes. Set it again before future doctor or run commands, or provide it through an appropriate local secret manager.

3. Install tunnel-client.exe

Download the Windows tunnel client using the instructions in the Secure MCP Tunnel guide and place it somewhere local, for example:

C:\Users\YOUR_USER\Downloads\tunnel-client.exe

Check the binary:

C:\Users\YOUR_USER\Downloads\tunnel-client.exe --version
C:\Users\YOUR_USER\Downloads\tunnel-client.exe --help

4. Find the Poetry Python executable

From the repository directory, run:

poetry env info --path

For example:

C:\Users\YOUR_USER\AppData\Local\pypoetry\Cache\virtualenvs\telegram-mcp-bridge-xxxx-py3.13

The Python executable is therefore:

C:/Users/YOUR_USER/AppData/Local/pypoetry/Cache/virtualenvs/telegram-mcp-bridge-xxxx-py3.13/Scripts/python.exe

Use forward slashes inside the tunnel profile command. Backslashes may be treated as escape characters and produce a broken path such as C:UsersYOUR_USER....

Verify the module before creating the profile:

C:/Users/YOUR_USER/AppData/Local/pypoetry/Cache/virtualenvs/telegram-mcp-bridge-xxxx-py3.13/Scripts/python.exe -c "import telegram_mcp_bridge; print('OK')"

5. Create the tunnel-client profile

Run from the repository directory so the child MCP process can find .env:

cd C:\Users\YOUR_USER\Documents\Code\Telegram_MCP_Bridge
C:\Users\YOUR_USER\Downloads\tunnel-client.exe init --profile telegram-mcp --tunnel-id tunnel_REPLACE_ME --mcp-command "C:/Users/YOUR_USER/AppData/Local/pypoetry/Cache/virtualenvs/telegram-mcp-bridge-xxxx-py3.13/Scripts/python.exe -m telegram_mcp_bridge.server" --open-web-ui

Use one pair of double quotes around the complete --mcp-command. Unix single quotes ('''...''') do not group arguments in Windows cmd.exe. If a broken profile already exists, add --force:

C:\Users\YOUR_USER\Downloads\tunnel-client.exe init --force --profile telegram-mcp --tunnel-id tunnel_REPLACE_ME --mcp-command "C:/Users/YOUR_USER/AppData/Local/pypoetry/Cache/virtualenvs/telegram-mcp-bridge-xxxx-py3.13/Scripts/python.exe -m telegram_mcp_bridge.server" --open-web-ui

Profiles are normally stored at:

C:\Users\YOUR_USER\AppData\Roaming\tunnel-client\telegram-mcp.yaml

6. Diagnose and run the tunnel

In the same terminal containing CONTROL_PLANE_API_KEY:

cd C:\Users\YOUR_USER\Documents\Code\Telegram_MCP_Bridge
C:\Users\YOUR_USER\Downloads\tunnel-client.exe doctor --profile telegram-mcp
C:\Users\YOUR_USER\Downloads\tunnel-client.exe run --profile telegram-mcp

Keep run open for connector discovery and every later MCP call. With --open-web-ui, the local admin UI opens automatically. A healthy setup shows the main channel as enabled, server external, and transport stdio.

7. Create the ChatGPT plugin

While tunnel-client run is active:

1. Open ChatGPT Settings -> Plugins -> New plugin.

2. Enter a name such as Telegram MCP Bridge.

3. Select Tunnel, not Server URL.

4. Select the tunnel ID created above.

5. No separate OAuth configuration is required by this local bridge.

6. Confirm the custom MCP warning and create the plugin.

7. Start a new chat with the plugin enabled and ask it to list Telegram chats.

When the MCP tool schema changes, update/reconnect the plugin and start a new conversation. Existing conversations may retain the older tool list.

Update and restart

cd C:\Users\YOUR_USER\Documents\Code\Telegram_MCP_Bridge
git pull
poetry install

Stop the running tunnel with Ctrl+C, set CONTROL_PLANE_API_KEY in the new terminal, and run it again:

set "CONTROL_PLANE_API_KEY=sk-REPLACE_ME"
cd C:\Users\YOUR_USER\Documents\Code\Telegram_MCP_Bridge
C:\Users\YOUR_USER\Downloads\tunnel-client.exe run --profile telegram-mcp

Troubleshooting

401 Unauthorized in tunnel-client logs

The control-plane key is missing, invalid, revoked, or belongs to a different Platform organization. Stop the daemon, set a valid runtime key in the same cmd.exe window, and restart it. Confirm the tunnel and key belong to the same organization and the account has Tunnels Read + Use.

unknown shorthand flag: 'm' in -m

The MCP command was not enclosed in Windows double quotes. Use:

--mcp-command "C:/absolute/path/to/python.exe -m telegram_mcp_bridge.server"

Executable path becomes C:Users...

Backslashes were consumed as escapes. Recreate the profile with --force and forward slashes in --mcp-command.

Telegram session is not authorized

Stop the tunnel, authorize from the repository, then restart it:

cd C:\Users\YOUR_USER\Documents\Code\Telegram_MCP_Bridge
poetry run telegram-mcp-login

Connector creation returns Something went wrong

Keep the tunnel daemon running and inspect its local Logs page while trying again. If no connector request reaches the daemon, verify the tunnel-to-ChatGPT workspace association. If a request arrives and fails, run doctor and inspect the MCP subprocess error.

Generic stdio MCP configuration

For a local MCP host that supports direct stdio processes, start the server with:

telegram-mcp

Example MCP configuration:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "replace_me",
        "TELEGRAM_SESSION_PATH": "/absolute/path/to/private/telegram_mcp"
      }
    }
  }
}

On Windows, point command to .venv\\Scripts\\telegram-mcp.exe.

Access policy

Set TELEGRAM_ALLOWED_CHAT_IDS to a comma-separated allowlist. When it is empty, all ordinary cloud chats visible to the account are accessible. For safer use, begin with one or two chat IDs returned by telegram_list_chats.

Limits are controlled with:

• TELEGRAM_MAX_MESSAGES_PER_REQUEST (default: 100)

• TELEGRAM_MAX_SEARCH_RESULTS (default: 100)

telegram_get_image returns JPEG, PNG, GIF, and WebP attachments directly as MCP image content. Downloads stay in memory and are capped by TELEGRAM_MAX_MEDIA_BYTES (default: 10 MiB).

Security

The .session file grants access to the Telegram account. Never commit or share it. Keep the bridge local, use an allowlist, and review every MCP host that can invoke it.