mcp-telegram-bridge

Ponte MCP via stdio para a API do Telegram Bot, com limpeza de dados e lista de permissão de chats.

Documentação

mcp-telegram-bridge

Ponte controlada de canal Telegram para qualquer host MCP.

Um pequeno servidor stdio Model Context Protocol que fica entre seu agente local (Cursor, Claude Desktop, Windsurf, agentes Grok/Cursor e outros) e a API de Bot do Telegram. O agente é dono da lógica de conversação; este processo lida com I/O, limpeza de saída sempre ativa e aplicação da lista de permissões de chat. Classificação estrita de entrada opcional está desabilitada por padrão.

Construído para implantações de propriedade do cliente: a ponte roda na sua máquina, não em uma VM Grok hospedada. Jogos e fluxos de mestre de jogo são um caso de uso de demonstração, não o produto.

Contexto do proprietário: Antonio Castellon / Castellon.CH - arquiteto freelancer suíço. O mesmo formato de ponte é útil para padrões de laboratório de PMEs (canais de notificação, transferência de especialistas, rascunhos moderados) junto com conectores de e-mail ou ERP.

O quê / por quê

Agentes são bons em raciocínio e ruins em manter uma sessão bruta da API do Bot por conta própria. O Telegram é uma superfície humana conveniente (grupos, botões, celular). Este projeto oferece uma ponte estreita e revisável:

De propriedade do cliente - stdio MCP na estação de trabalho ou runner de CI que já hospeda seu agente.
Agnóstico de host - qualquer cliente MCP que possa iniciar um comando local.
Controlado - limpeza de saída e ALLOWED_CHAT_IDS opcional; classificação estrita de entrada opcional para grupos não confiáveis.
Ferramentas mínimas - enviar, editar markup, responder callbacks, obter atualizações, getMe / getChat. Sem motor de jogo, sem arquivo de caixa de entrada, sem wake-RPC.

Padrão de proposta para PMEs: comece com um canal de notificação ou triagem do Telegram usando a mesma arquitetura que você aplicaria depois a e-mail ou ERP.

Arquitetura

  +---------------------------+
  |  MCP host / agents        |  Cursor / Claude Desktop / Windsurf / ...
  |  (conversation logic)     |
  +-------------+-------------+
                |
                |  MCP (stdio)
                v
  +---------------------------+
  |  mcp-telegram-bridge      |  tools + safety scrub/classify
  |  (this process)           |
  +-------------+-------------+
                |
                |  HTTPS Bot API
                v
  +---------------------------+
  |  api.telegram.org         |
  +-------------+-------------+
                v
         Telegram chats / groups

O agente é dono dos offsets de polling, transferências entre especialistas e política de produto. Este servidor aplica controles de destino e envia texto limpo; classificação de entrada é opcional.

Instalação

Requisitos: Python 3.11+, um token de bot do Telegram do @BotFather.

git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
cd mcp-telegram-bridge
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env        # set TELEGRAM_BOT_TOKEN (never commit .env)

Ou sem clonar, quando publicado:

uvx --from mcp-telegram-bridge mcp-telegram-bridge
# or: pipx run mcp-telegram-bridge

Cursor / Claude Desktop (`mcp.json`)

Exemplo para Cursor (configurações de MCP do usuário) ou Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram-bridge": {
      "command": "uvx",
      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "ALLOWED_CHAT_IDS": "-1001234567890"
      }
    }
  }
}

No Windows, aponte command para o Python do seu venv se necessário, por exemplo:

C:\DEV.Personal\mcp-telegram-bridge\.venv\Scripts\python.exe

Deixe ALLOWED_CHAT_IDS vazio somente se você aceitar intencionalmente tráfego de qualquer chat que o bot possa ver - documente esse risco para sua implantação.

Teste rápido sem host:

python -m mcp_telegram_bridge
# process waits on stdio for MCP JSON-RPC (Ctrl+C to stop)

Ferramentas MCP

Ferramenta	Propósito
`telegram_get_me`	Verificação de identidade / conectividade do bot
`telegram_send_message`	`chat_id`, `text`, `parse_mode` opcional, `buttons=[{id,label}]` opcional
`telegram_edit_reply_markup`	Remover ou substituir botões inline
`telegram_answer_callback`	Confirmar um `callback_query_id` (toast opcional)
`telegram_get_updates`	`offset`, `limit`, `timeout` - retorna mensagens + callback_queries; o agente é dono do loop
`telegram_get_chat`	Metadados do chat

Texto de saída é sempre limpo. ALLOWED_CHAT_IDS restringe destinos quando configurado. telegram_get_updates executa o classificador heurístico de segredos/NSFW somente quando SAFETY_STRICT=1 (ou true/yes/on); o modo estrito é opcional e recomendado para grupos públicos ou não confiáveis.

Guia de uso

Agentes colaborativos em um grupo do Telegram

Execute um processo de ponte por bot (ou um bot com papéis de agente claros). Use o grupo para notas de standup, filas de triagem e transferência entre agentes especialistas ("ops confirma; billing redige a resposta"). Mantenha humanos no loop para ações irreversíveis.

Mestre de jogo / facilitador de mesa (demonstração)

Envie texto de cena com buttons=[{id,label}, ...] para escolhas dos jogadores; em callback_query, responda ao callback, opcionalmente com tratamento de primeiro toque estilo claim no agente, depois edite o markup para limpar escolhas gastas. Isso é uma demonstração de botões + loop de agente - não um motor de RPG embutido.

Canal de notificação de suporte / operações

Envie alertas com botões de confirmação (ack, snooze, escalate). O agente registra quem tocou no quê; o Telegram é a superfície de pager, não a fonte da verdade.

Assistente de moderação de comunidade

Redija respostas e sugira ações. Humanos ainda são donos de banir / restringir / excluir no Admin do Telegram - diga isso no prompt do seu agente. A ponte não deve ser tratada como autoridade de moderação.

Padrão de laboratório / PME

Mesmo formato de um conector de e-mail ou ERP: ferramentas estreitas, destinos na lista de permissões, saída limpa, avisos explícitos de entrada. O Telegram é o canal de demonstração; troque o transporte depois sem reescrever a política do agente.

O que isto NÃO é

Não é um SaaS de bot hospedado ou ponte em nuvem multi-tenant
Não é exclusivo do Grok (funciona com qualquer host stdio MCP)
Não é um motor completo de RPG / jogo (sem regras de dados, sem banco de dados de campanha neste repositório)
Não é um bot admin sem supervisão (sem ferramentas de banimento aqui)

Relação com demos irmãos

Contexto opcional apenas - este projeto não os exige:

grokgame - superfície de demonstração de mesa / jogo
grok2telegram - experimento de ponte anterior cuja doutrina de segurança informou SAFETY.md e safety.py

mcp-telegram-bridge é a extração reutilizável e agnóstica de host: I/O + segurança, sem loop de jogo e sem lógica de wake de VM Grok.

Segurança

Veja SAFETY.md para o modelo de ameaças, limpeza sempre ativa e controles de lista de permissões, tratamento de tokens, modo estrito opcional e diretório de dados de mapa de botões (MCP_TELEGRAM_BRIDGE_DATA_DIR, modos 0700/0600). Não coloque segredos no repositório; prefira ALLOWED_CHAT_IDS em configurações semelhantes a produção.

Desenvolvimento

pip install -e ".[dev]"
pytest

Testes simulam HTTP do Telegram com respx / httpx; nenhum token ao vivo é necessário.

Registro MCP

Nome canônico: io.github.antonio-castellon/mcp-telegram-bridge

Também listado em mcpservers.org e MCP Marketplace.

Para preenchimento automático de listagem no marketplace, veja LAUNCHGUIDE.md (tagline, variáveis de ambiente de configuração, categoria, casos de uso e exemplos de prompts).

Licença

MIT (c) Antonio Castellon / Castellon.CH

mcp-telegram-bridge

Documentação