What can you do with this server?

This server acts as a read-only bridge to your personal Telegram account via MTProto, letting AI assistants browse and search your Telegram messages without sending, editing, or deleting anything. * telegram_list_chats: List Telegram cloud chats, with optional limit and archived chat filter. * telegram_get_messages: Read messages from a specific chat (newest first), with pagination via limit and before_message_id, without marking them as read. * telegram_search_messages: Search for text globally across all allowed chats or within a specific chat. * telegram_get_message_context: Retrieve a target message along with surrounding messages (configurable before/after count) in chronological order. * telegram_get_chat_info: Fetch basic metadata (name, type, member count, etc.) for a specific chat. * telegram_get_image (noted in README but not in schema): Download image attachments (JPEG, PNG, GIF, WebP) as MCP image content, capped by a configurable size limit. Key constraints: * Read-only: Cannot send, edit, delete, forward, or mark messages as read. * Access control: Can be restricted to specific chat IDs via an allowlist. * Local only: Runs locally; remote access can be facilitated through a secure tunnel.

Which integrations are available for this server?

Provides read-only access to a Telegram user account, allowing listing chats, retrieving messages, searching messages, getting message context, and getting chat information.

How do I use Telegram MCP Bridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Telegram MCP Bridge show me the last 10 messages from my Python group chat" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Telegram MCP Bridge

by boltholds

Overview Schema Related Servers Score Discussions

Python

Local

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.

Создайте приложение на https://my.telegram.org и сохраните api_id и api_hash.
В OpenAI Platform → Tunnels создайте туннель и скопируйте значение вида tunnel_....
В OpenAI Platform → API keys создайте Runtime API key для туннеля. Admin key для запуска не нужен.
Скопируйте .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

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

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, затем:

укажите номер Telegram в международном формате;
введите код, пришедший от Telegram;
если включена двухэтапная аутентификация, введите пароль 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

Переменная	Назначение	По умолчанию
`TUNNEL_ID`	ID Secure MCP Tunnel	обязательна
`CONTROL_PLANE_API_KEY`	Runtime API key	обязательна
`ADMIN_USERNAME`	логин веб-панели	`admin`
`ADMIN_PASSWORD`	пароль веб-панели	обязательна для панели
`WEB_PANEL_PORT`	локальный порт панели/MCP	`8765`
`TUNNEL_HEALTH_PORT`	локальный health-порт tunnel-client	`8080`
`TUNNEL_CLIENT_VERSION`	закреплённая версия образа	`0.0.10`

Порты публикуются только на 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

Sign in at https://my.telegram.org.
Open API development tools.
Create an application and copy its api_id and api_hash.
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

Open OpenAI Platform tunnel settings.
Select the same Platform organization used by the target ChatGPT account.
Create a tunnel, for example telegram-mcp.
Associate it with the target personal ChatGPT workspace (or the required Business/Enterprise workspace).
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:

Open ChatGPT Settings -> Plugins -> New plugin.
Enter a name such as Telegram MCP Bridge.
Select Tunnel, not Server URL.
Select the tunnel ID created above.
No separate OAuth configuration is required by this local bridge.
Confirm the custom MCP warning and create the plugin.
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.

Available Tools

5 tools

telegram_get_chat_infoB

Return basic metadata for one allowed chat.

ParametersJSON Schema

Name	Required	Description	Default
`chat_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full burden. It states 'Return' implying a read-only operation, but lacks details on side effects, permissions, or rate limits. For a simple get operation, this is minimal but acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core purpose without unnecessary words. It is well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter and an output schema, the description is minimally sufficient. However, it lacks behavioral details (e.g., what 'basic metadata' includes) and parameter guidance, leaving some gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate but does not. It fails to mention the required 'chat_id' parameter or its format/meaning. The schema provides a title 'Chat Id' but the description adds no value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Return basic metadata for one allowed chat' clearly states the verb (return) and specific resource (basic metadata for one allowed chat). It distinguishes this tool from siblings like telegram_get_messages (which returns messages) and telegram_list_chats (which lists multiple chats).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for getting metadata of a single chat, contrasting with siblings that handle lists or messages. However, it provides no explicit guidance on when to use or not use this tool, nor any alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

telegram_get_message_contextC

Read a target message together with nearby messages in chronological order.

ParametersJSON Schema

Name	Required	Description	Default
`after`	No
`before`	No
`chat_id`	Yes
`message_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden for behavioral traits. It implies a read-only, non-destructive operation, but does not disclose auth requirements, rate limits, or whether the returned order is guaranteed. The existence of an output schema mitigates some concerns, but the description adds minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core purpose without unnecessary words. While brief, it is front-loaded and not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, no annotations, and a moderate output schema, the description is too sparse. It fails to explain parameter meanings or provide usage context, leaving the agent to infer from parameter names alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it does not explain any parameter. 'Target message' hints at message_id, and 'nearby messages' hints at after/before, but no semantics or default behaviors are provided. Parameters remain opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reads a target message with nearby messages in chronological order, distinguishing it from sibling tools like telegram_get_messages (likely returns messages without context) and telegram_search_messages. However, it could explicitly mention parameters (after, before) that define 'nearby'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings such as telegram_get_messages or telegram_search_messages. The description does not mention prerequisites, limitations, or alternative tools, leaving the agent without decision context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

telegram_get_messagesA

Read messages from one allowed chat, newest first, without marking them read.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`chat_id`	Yes
`before_message_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It explicitly states two important behaviors: messages are returned 'newest first' (ordering) and are 'without marking them read' (side effect). This is valuable context beyond the input schema. However, it does not mention other behaviors like pagination mechanics or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 12-word sentence that packs purpose, ordering, and side effect without any filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and an output schema, the description provides core information but lacks details on pagination (before_message_id), limit semantics, and prerequisites (e.g., chat must be allowed). It is adequate for basic understanding but incomplete for advanced usage. The output schema covers return structure, so that gap is partially filled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate by explaining parameters. It does not. The description only says 'Read messages from one allowed chat' without referencing chat_id, limit, or before_message_id. The parameter names are somewhat self-explanatory, but no added semantics like how to paginate using before_message_id are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read messages', the resource 'from one allowed chat', and two key traits: 'newest first' and 'without marking them read'. This distinguishes it from sibling tools like telegram_list_chats which lists chats, and telegram_search_messages which searches across chats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for reading messages from a specific chat without marking them as read, but does not explicitly state when to use this tool versus alternatives like telegram_search_messages or telegram_get_message_context. No when-not-to-use or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

telegram_list_chatsB

List Telegram cloud chats allowed by the local access policy.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`archived`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must disclose behavioral traits. It implies a read-only, non-destructive operation and adds the access policy constraint. However, it omits details such as pagination behavior, authentication requirements, or what the output contains, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant words. Every word earns its place, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 optional parameters) and the existence of an output schema, the description is minimally adequate. It covers the core purpose but fails to describe the return format or any filtering behavior beyond the access policy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain the two parameters (limit, archived). It does not mention them at all. While the parameter names are somewhat intuitive, the description adds no semantic value beyond what a user might guess.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('Telegram cloud chats'), and adds a distinguishing constraint ('allowed by the local access policy'), which differentiates it from sibling tools like telegram_get_chat_info that retrieve details of a single chat.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as telegram_get_chat_info or telegram_search_messages. The description lacks context for selecting the tool appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

telegram_search_messagesC

Search text globally or inside one allowed Telegram chat.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`chat_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided and description does not disclose behavioral traits such as rate limits, authentication requirements, side effects, or return format. Only states basic action without deeper context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, concise but lacks structure. Does not break down key details or parameter usage. Could be more informative without adding length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has moderate complexity (3 params, output schema exists) but description is minimal. Does not explain return values or how search results are structured, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; description adds no explanation for the three parameters (query, limit, chat_id). The schema provides names and types but no semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Search) and resource (text), and distinguishes between global search and searching within a specific chat. However, 'allowed' is slightly ambiguous regarding permissions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs siblings like telegram_get_messages or telegram_get_message_context. Does not mention alternatives or provide when-not conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0Jul 14, 2026
- First observedtelegram_get_chat_info
- First observedtelegram_get_message_context
- First observedtelegram_get_messages
- First observedtelegram_list_chats
- First observedtelegram_search_messages

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Disambiguation5/5

Each tool has a clear, distinct purpose: listing chats, getting chat info, retrieving messages, getting message context with surrounding messages, and searching. No overlap in functionality.

Naming Consistency5/5

All tools follow the consistent pattern 'telegram_verb_noun', with verbs like get, list, search used predictably.

Tool Count4/5

5 tools is appropriate for a focused read-only Telegram bridge, covering core operations without being excessive or insufficient.

Completeness3/5

The tool set covers reading and searching but lacks send, delete, or chat management operations, which are notable gaps for a Telegram bridge if write capabilities are expected.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

fast-mcp-telegram A
io.github.leshchenko1979
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Communication
8249
Synci AOAuth
io.synci
Read-only access to your bank, investment, and crypto accounts: balances, transactions, holdings.
Finance
2
VocciOAuth
ai.vocci
Read-only MCP access to authorized Vocci sessions, notes, files, and memory search.
Note Taking Knowledge & Memory
2
telegram C
com.jojapi
Telegram: FASTEST real time Telegram API. Retrieve channel's info and messages in milliseconds..
Communication Social Media
21

Related MCP Servers

tdl-mcp
Communication
rixile9999
A
license
A
quality
D
maintenance
Read-only Telegram access for Claude and other MCP hosts. Provides tools to list chats, read recent messages, and download media from your own Telegram account without needing an api_id/api_hash.
Updated 2 days ago (2026-09-04 13:45 UTC)
5
MIT
telegram-mcp
Communication Search
Shaan-alpha
A
license
Not graded
quality
C
maintenance
Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
Updated 2 days ago (2026-09-04 11:41 UTC)
1
MIT
my-tg-mcp
kiaquila
-
license
Not graded
quality
B
maintenance
Read-only MCP access to a personal Telegram account. Allows querying chats, reading and searching messages via Streamable HTTP.
Updated 2 months ago (2026-07-22 00:39 UTC)
-
telegram-mcp
Communication Search
nskondratev
A
license
Not graded
quality
C
maintenance
A read-only Telegram MCP server that only exposes a user-defined allowlist of chats, providing tools to list chats, fetch messages, search, and get context while stripping untrusted text and with no write capabilities.
Updated a month ago (2026-08-03 21:58 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/boltholds/Telegram_MCP_Bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Telegram MCP Bridge

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

Настройки Docker

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

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

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

401 Unauthorized от control plane

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

Current tools

Requirements

Windows installation with Poetry

Telegram API credentials

Connect ChatGPT through Secure MCP Tunnel

1. Create a tunnel and copy its ID

2. Create the runtime API key

3. Install tunnel-client.exe

4. Find the Poetry Python executable

5. Create the tunnel-client profile

6. Diagnose and run the tunnel

7. Create the ChatGPT plugin

Update and restart

Troubleshooting

401 Unauthorized in tunnel-client logs

unknown shorthand flag: 'm' in -m

Executable path becomes C:Users...

Telegram session is not authorized

Connector creation returns Something went wrong

Generic stdio MCP configuration

Access policy

Security

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

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

`401 Unauthorized` от control plane

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

`401 Unauthorized` in tunnel-client logs

`unknown shorthand flag: 'm' in -m`

Executable path becomes `C:Users...`

`Telegram session is not authorized`

Connector creation returns `Something went wrong`