Telegram MCP Server

Interaja com o serviço de mensagens Telegram para enviar e receber mensagens.

Documentação

Uma integração Telegram para Claude, Cursor e outros clientes compatíveis com MCP. Ela expõe operações de conta, chat, mensagem, contato, mídia, pasta e administração do Telegram por meio do Model Context Protocol usando Telethon.

🤖 MCP em Ação

Uso básico do Telegram MCP no Claude:

Pedindo ao Claude para analisar o histórico do chat e enviar uma resposta:

Mensagem enviada com sucesso:

O Que Ele Pode Fazer

O servidor atualmente inclui mais de 80 ferramentas MCP agrupadas nestas áreas:

Contas: liste contas configuradas e direcione chamadas de ferramentas pelo rótulo da conta.
Chats e grupos: liste chats, inspecione metadados, crie grupos/canais, entre ou saia de chats, convide usuários, gerencie administradores, banimentos, permissões padrão, modo lento, tópicos, links de convite, chats em comum, recibos de leitura e links de mensagem.
Mensagens: envie, agende, edite, exclua, encaminhe, fixe, desafixe, marque como lida, responda, pesquise, inspecione o contexto, crie enquetes, gerencie reações, inspecione botões inline e pressione callbacks inline. send_message, reply_to_message e edit_message suportam formatação clássica (parse_mode='md'/'html') e formatação rica no lado do servidor (parse_mode='rich'/'rich_markdown'/'rich_html' — Markdown/HTML completo com tabelas, títulos, fórmulas e seções recolhíveis). Os modos ricos exigem Telegram Premium na conta; o Premium é verificado novamente a cada chamada e, sem ele, nada é enviado — a ferramenta retorna um resultado estruturado telegram_premium_required para que o agente possa reformatar com os modos clássicos e tentar novamente.
Contatos: liste, pesquise, adicione, exclua, bloqueie, desbloqueie, importe, exporte, inspecione chats diretos, encontre interações recentes com contatos e lembre-se dos contatos pelos nomes que você realmente usa (veja abaixo).

Contatos lembrados

set_contact_alias ensina ao servidor como você chama alguém, e toda ferramenta que recebe um chat_id entende isso a partir de então — send_message("андрей бекендер", ...) simplesmente funciona. Um contato pode carregar qualquer número de apelidos, que é como as tags funcionam: salve tanto андрей бекендер quanto бекендер para a mesma pessoa e qualquer um deles resolve.

Somente uma redação exata salva é enviada. Redações semelhantes (Андрею бекендеру para um андрей бекендер salvo) também são correspondidas, mas apenas para sugerir: a ferramenta não envia nada e pede que você confirme o contato pelo nome. Isso é proposital — Лена/Леня e Иван/Иванов diferem exatamente tanto quanto uma desinência de caso, então um correspondente confiante o suficiente para lidar com declinações também é confiante o suficiente para enviar mensagem para a pessoa errada sempre que a que você quis dizer ainda não estiver salva. Confirmar salva essa redação como um apelido próprio, então cada nova formulação custa um sim/não na primeira vez e nada depois disso. Defina TELEGRAM_CONTACT_FUZZY=0 para também descartar as sugestões.

Quando uma referência é desconhecida, se assemelha a um contato, corresponde a vários ou aponta para um contato que não resolve mais, as ferramentas não enviam nada e retornam uma instrução estruturada dizendo ao agente exatamente o que perguntar a você, para salvar a resposta com set_contact_alias e tentar novamente uma vez. list_contact_aliases mostra uma linha por pessoa com todos os seus apelidos (use para identificar uma memória errada), delete_contact_alias esquece um, e redirecionar um apelido para outra pessoa exige replace=True. O próprio caminho de salvamento recusa um alvo que teria que adivinhar: contatos são salvos por @username, telefone, ID numérico ou um apelido já confirmado para eles.

Os apelidos ficam em ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/aliases.json (somente proprietário, gravado atomicamente); TELEGRAM_ALIASES_FILE substitui o caminho, e um aliases.json pré-existente ao lado do código ainda é lido como fallback.

Mídia: envie arquivos, baixe mídia, faça upload de arquivos, envie notas de voz, figurinhas, GIFs e inspecione a mídia de mensagens.
Perfil e privacidade: obtenha informações da sua própria conta, atualize campos do perfil, defina ou exclua fotos de perfil, inspecione configurações de privacidade, obtenha informações/fotos/status de usuários e gerencie comandos de bot.
Pastas e rascunhos: liste, crie, atualize, reordene e exclua pastas do Telegram; salve, liste e limpe rascunhos.
Eventos: aguarde mensagens recebidas com debounce (wait_for_new_message, wait_for_settled_message), opcionalmente para apenas um chat via chat_id — sem ele, qualquer conversa não relacionada interrompe a espera — ou ative o feed de eventos recebidos opcional para entrega no estilo callback (veja abaixo).

Todos os resultados de ferramentas que incluem conteúdo controlado pelo usuário do Telegram são sanitizados e, quando prático, retornados como JSON estruturado.

Feed de Eventos Recebidos (modo callback, apenas Claude Code)

Por padrão, um agente aguarda respostas chamando wait_for_settled_message, que bloqueia até o timeout da ferramenta MCP e deve ser chamado novamente — isso funciona em qualquer lugar (Codex, Cursor, etc.) e permanece inalterado.

Clientes que podem acordar um agente com saída externa (o Monitor persistente do Claude Code em tail -f) podem alternar para o modo callback:

O agente chama enable_incoming_feed (ou defina TELEGRAM_EVENT_FEED=1 no ambiente para ativação automática). Cada rajada recebida estabilizada é anexada como uma linha JSON em ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/incoming_feed.jsonl, criado somente para o proprietário (0600). Substitua o caminho com TELEGRAM_EVENT_FEED_FILE — o diretório de um caminho explícito já deve existir. incoming_feed_status informa o caminho efetivo e um comando watch pronto para uso.
O agente arma um Monitor persistente com o watch_command retornado pela ferramenta. Cada nova linha re-invoca o agente com o resumo da rajada; nenhuma chamada de ferramenta bloqueante fica aberta e o chat permanece livre.

disable_incoming_feed volta ao modo anterior; incoming_feed_status informa o modo atual. Enquanto o feed estiver ativado, ele consome rajadas estabilizadas, então não o combine com wait_for_settled_message. As linhas do feed contêm campos name gerados pelo usuário — trate-os como dados não confiáveis.

Requisitos

Python 3.10+
Credenciais da API do Telegram em my.telegram.org/apps
Uma string de sessão do Telegram ou sessão baseada em arquivo
Um cliente MCP como Claude Desktop, Cursor ou outro host compatível com MCP
Opcional: uv para desenvolvimento local

Início Rápido

Não instale este servidor com uvx telegram-mcp, uvx --from telegram-mcp, ou pip install telegram-mcp. O nome telegram-mcp no PyPI é atualmente de propriedade de um projeto diferente e não instala este repositório. Passar TELEGRAM_API_ID, TELEGRAM_API_HASH ou TELEGRAM_SESSION_STRING para esse pacote pode expor credenciais de conta do Telegram a código de terceiros não relacionado.

1. Clone e Instale

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

2. Gere uma String de Sessão

uv run session_string_generator.py

Siga as instruções. Salve a string de sessão gerada com segurança.

Para configuração por script ou runbooks operacionais, escolha o método de login explicitamente:

# QR login, recommended when you already have Telegram open on another device
uv run session_string_generator.py --qr

# Phone number + verification code login
uv run session_string_generator.py --phone

Sem uma flag, o gerador mantém o prompt interativo do método.

3. Configure o Ambiente

Copie o arquivo de exemplo e preencha com seus valores reais:

cp .env.example .env

Configuração de conta única:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING=your_session_string_here

Por padrão, todas as ferramentas MCP do Telegram são expostas. Se você quiser impedir que clientes MCP enviem mensagens ou realizem mutações de chat/conta, defina TELEGRAM_EXPOSED_TOOLS=read-only para expor apenas ferramentas anotadas com readOnlyHint=True:

TELEGRAM_EXPOSED_TOOLS=read-only

Se somente leitura for restritivo demais, mas all for amplo demais, acrescente + e uma lista separada por vírgulas de nomes de ferramentas para também expor essas ferramentas de escrita específicas. Toda outra ferramenta de escrita permanece não registrada:

TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message,send_file

Um nome desconhecido na lista de permissões aborta a inicialização, para que um erro de digitação não possa silenciosamente degradar para uma superfície mais restrita que parece ter funcionado.

Esta é uma restrição de superfície de ferramentas MCP, não uma sandbox de sessão do Telegram ou permissão reduzida de conta do Telegram. A string de sessão do Telegram ainda tem sua autoridade normal dentro do processo do servidor; o modo somente leitura apenas impede que ferramentas não somente leitura sejam registradas e expostas via MCP. Valores aceitos são all (o padrão), read-only e read-only+<tool>,<tool>.

Execute o servidor localmente:

uv run main.py

Configuração do Cliente MCP

Para Claude Desktop ou Cursor, aponte o servidor MCP para um checkout clonado deste projeto:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Para expor apenas ferramentas somente leitura no Claude Desktop ou Cursor, adicione isto ao bloco env do servidor:

"TELEGRAM_EXPOSED_TOOLS": "read-only"

Ou mantenha somente leitura como base e permita algumas ferramentas de escrita adicionais:

"TELEGRAM_EXPOSED_TOOLS": "read-only+send_message,reply_to_message"

Alternativamente, instale este repositório diretamente do GitHub em um ambiente virtual usando uma tag de release ou commit específico:

python -m venv .venv
. .venv/bin/activate
pip install "git+https://github.com/chigwell/telegram-mcp.git@<tag-or-commit>"

Em seguida, configure seu cliente MCP para executar o script de console instalado:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "/full/path/to/.venv/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Gere uma string de sessão sem clonar o repositório, referenciando este repositório do GitHub explicitamente:

uvx --from "git+https://github.com/chigwell/telegram-mcp.git@<pinned-release-tag-or-commit>" telegram-mcp-generate-session

Transportes

O servidor suporta três transportes MCP, selecionados com MCP_TRANSPORT:

Valor	Transporte	Caso de uso
`stdio`	stdio (padrão)	Um processo de servidor dedicado por cliente MCP
`http`	streamable HTTP	Um servidor compartilhado para muitos clientes (Claude Code, Codex, Cursor)
`sse`	SSE (HTTP legado)	Clientes que só suportam o transporte SSE descontinuado

Para http e sse, o servidor vincula MCP_HOST:MCP_PORT (padrão 127.0.0.1:8765); o endpoint de streamable HTTP é /mcp, o endpoint SSE é /sse.

Se o servidor for acessível por um domínio (por exemplo, atrás de um proxy reverso) em vez de apenas 127.0.0.1/localhost, defina MCP_ALLOWED_HOSTS (e opcionalmente MCP_ALLOWED_ORIGINS) para ativar a proteção contra DNS rebinding e permitir esse cabeçalho Host, por exemplo, MCP_ALLOWED_HOSTS=mcp.example.com. Separado por vírgulas; suporta um sufixo :* para permitir qualquer porta. Se não for definido, a proteção contra DNS rebinding permanece desativada (o padrão histórico).

Prefira http quando mais de um cliente MCP (ou muitas sessões de agente de codificação) usarão o servidor: um único processo de longa duração mantém uma conexão Telegram, em vez de cada cliente criar sua própria sessão Telethon — o Telegram limita e pode sinalizar contas que abrem muitas sessões paralelas.

Registre o servidor compartilhado com os clientes:

# Claude Code
claude mcp add --transport http telegram http://127.0.0.1:8765/mcp

# Codex
codex mcp add telegram --url http://127.0.0.1:8765/mcp

Para clientes somente stdio, faça a ponte com mcp-remote:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp"]
    }
  }
}

Configuração de Múltiplas Contas

Use variáveis de sessão com sufixo para configurar múltiplas contas do Telegram:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING_WORK=session_string_for_work
TELEGRAM_SESSION_STRING_PERSONAL=session_string_for_personal

Os rótulos são convertidos para minúsculas e se tornam o valor do parâmetro account nas ferramentas.

No modo de conta única, account é opcional.
No modo de múltiplas contas, ferramentas de escrita exigem account.
Ferramentas somente leitura se distribuem para todas as contas quando account é omitido.

Exemplos de prompts:

"Liste minhas contas"
"Mostre mensagens não lidas de todas as contas"

Pool de sessões (uma conta, vários clientes concorrentes)

Para executar vários clientes MCP contra a mesma conta do Telegram ao mesmo tempo (por exemplo, o aplicativo de desktop e um CLI de terminal), dê a cada cliente sua própria sessão autorizada. O Telegram proíbe que uma sessão (chave de autenticação) seja usada a partir de dois IPs simultaneamente, então em uma VPN ou host dual-stack dois clientes locais podem colidir com AuthKeyDuplicatedError. Liste várias strings de sessão intercambiáveis em TELEGRAM_SESSION_STRINGS (separadas por espaço, vírgula ou ponto e vírgula); cada processo reivindica uma livre via um bloqueio de arquivo consultivo, então os clientes escolhem deterministicamente sessões distintas:

TELEGRAM_SESSION_STRINGS=<session A> <session B> <session C>

Gere sessões extras com uv run session_string_generator.py. O pool tem precedência sobre TELEGRAM_SESSION_STRING para a conta padrão. Como rede de segurança extra, um AuthKeyDuplicatedError transitório no momento da conexão (por exemplo, durante uma reconexão de VPN) é repetido com backoff antes que o servidor desista.

Dimensione o pool para o número de clientes que você realmente executa simultaneamente. Se cada slot já estiver reivindicado, o servidor se recusa a iniciar com um erro explícito em vez de reutilizar uma sessão que outro cliente possui — a reutilização faria o Telegram invalidar permanentemente essa sessão para ambos os clientes.

"Envie isso da minha conta de trabalho para @example"

Identidade do Dispositivo

Estas variáveis opcionais controlam como o cliente aparece no Telegram em Configurações > Dispositivos (a lista de sessões ativas):

TELEGRAM_DEVICE_MODEL=Telegram MCP
TELEGRAM_SYSTEM_VERSION=1.0
TELEGRAM_APP_VERSION=1.0

Se não forem definidas, o Telethon recorre à plataforma do host (por exemplo, arm64). Como esses valores são reenviados a cada conexão, um servidor de longa duração sobrescreveria o nome escolhido durante o login a cada reconexão, então defina-os para manter um nome de dispositivo estável e reconhecível. As mesmas variáveis são lidas tanto pelo gerador de string de sessão (no login) quanto pelo servidor (em cada conexão), então defina-as no mesmo lugar que suas outras credenciais.

Suporte a Proxy

Roteie o tráfego do Telegram através de um proxy definindo as variáveis de ambiente TELEGRAM_PROXY_*. Os tipos suportados são socks5, socks4, http e mtproxy.

Proxies SOCKS e HTTP exigem o pacote opcional python-socks:

uv sync --extra proxy
# or
pip install python-socks

Configuração de conta única:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USERNAME=optional_user
TELEGRAM_PROXY_PASSWORD=optional_pass
TELEGRAM_PROXY_RDNS=true

MTProxy:

TELEGRAM_PROXY_TYPE=mtproxy
TELEGRAM_PROXY_HOST=mtproxy.example
TELEGRAM_PROXY_PORT=443
TELEGRAM_PROXY_SECRET=ee0123456789abcdef...

Substituições por conta usam o mesmo sufixo _<LABEL> que as variáveis de sessão e têm precedência sobre os padrões sem sufixo:

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080

TELEGRAM_PROXY_TYPE_WORK=http
TELEGRAM_PROXY_HOST_WORK=proxy.work.example
TELEGRAM_PROXY_PORT_WORK=3128

Configurações de proxy mal configuradas (tipo desconhecido, host/porta ausentes, porta inválida, segredo MTProxy ausente ou pacote python-socks ausente) fazem o servidor falhar rapidamente na inicialização com uma mensagem de erro clara em vez de ignorar silenciosamente o proxy.

Segurança de Caminhos de Arquivo

As ferramentas de caminho de arquivo são desabilitadas até que raízes permitidas sejam configuradas. Isso afeta ferramentas como send_file, download_media, upload_file, send_voice, send_sticker, set_profile_photo e edit_chat_photo.

As raízes permitidas podem vir de:

Argumentos de CLI do servidor, usados como fallback.
Raízes do cliente MCP, quando suportadas pelo cliente.

Comportamento de segurança:

As raízes MCP do cliente substituem as raízes da CLI do servidor quando disponíveis.
Alguns clientes (notavelmente Cursor) retornam raízes de espaço de trabalho como caminhos absolutos simples em vez de URIs file://. Isso quebra a validação do SDK MCP de list_roots; o servidor recupera esses caminhos absolutos do erro de validação para que as ferramentas de caminho de arquivo continuem funcionando.
Raízes de cliente vazias são tratadas como negar-tudo por padrão. Alguns clientes implementam o recurso de Raízes, mas anunciam uma lista vazia, o que desabilita as ferramentas de arquivo mesmo quando as raízes da CLI do servidor estão configuradas. Defina TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=1 para recorrer às raízes da CLI do servidor nesse caso (opt-in; o padrão permanece negar-tudo). O mesmo opt-in também se aplica quando list_roots falha inesperadamente e nenhum caminho de cliente pôde ser recuperado.
Os caminhos são resolvidos através de caminhos reais e devem permanecer dentro de uma raiz permitida.
Padrões de travessia, curinga, shell e byte nulo são rejeitados.
Caminhos relativos são resolvidos sob a primeira raiz permitida.
Downloads padrão para <first_root>/downloads/.
Limites de tamanho e extensão são aplicados para ferramentas de mídia sensíveis.

Execute com raízes permitidas:

uv run main.py /data/telegram /tmp/telegram-mcp

A partir de uma configuração de cliente MCP, passe as mesmas raízes após main.py:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py",
        "/data/telegram",
        "/tmp/telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Docker

Construa a imagem:

docker build -t telegram-mcp:latest .

Servidor compartilhado (recomendado)

Execute um contêiner de longa duração servindo HTTP transmissível e aponte cada cliente MCP para ele (veja Transports para registro de cliente):

docker run -d --name telegram-mcp --restart unless-stopped \
  --env-file .env \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -p 127.0.0.1:8765:8765 \
  telegram-mcp:latest

MCP_HOST=0.0.0.0 vincula dentro do contêiner para que a porta publicada funcione; -p 127.0.0.1:8765:8765 mantém o servidor acessível apenas a partir da máquina local — o endpoint não é autenticado, então nunca o publique em uma interface pública.

O arquivo Compose incluído executa a mesma configuração:

docker compose up --build -d

Um contêiner por cliente (stdio)

Alternativamente, um cliente MCP pode iniciar um contêiner dedicado ele mesmo:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/full/path/to/.env", "telegram-mcp:latest"]
    }
  }
}

Isso é adequado para um único cliente, mas com vários clientes (ou agentes de codificação que iniciam sessões de subagentes) cada um inicia seu próprio contêiner e sua própria sessão do Telegram, o que o Telegram limita; um cliente que sai de forma não limpa também pode deixar seu contêiner em execução. Prefira o servidor compartilhado acima nesses cenários.

Para múltiplas contas, passe variáveis como TELEGRAM_SESSION_STRING_WORK e TELEGRAM_SESSION_STRING_PERSONAL.

Desenvolvimento

A implementação é dividida em um pequeno ponto de entrada de compatibilidade e código de pacote modular:

main.py                    # historical entrypoint and compatibility exports
telegram_mcp/runtime.py    # shared MCP setup, account routing, validation, file safety
telegram_mcp/runner.py     # application startup
telegram_mcp/tools/        # tool modules grouped by domain
sanitize.py                # output sanitization helpers
tests/                     # pytest suite

Execute os testes:

uv run pytest

Execute os testes com cobertura:

uv run pytest --cov --cov-report=term-missing --cov-report=xml

A cobertura é configurada em pyproject.toml com um limite mínimo de 80% para módulos principais determinísticos testáveis por unidade. GitHub Actions executa o mesmo comando de cobertura e envia coverage.xml.

Execute verificações de formatação:

uv run black --check .
uv run flake8 .

Notas de Segurança

Nunca envie .env, strings de sessão ou arquivos .session.
Uma string de sessão do Telegram concede acesso à conta à qual pertence.
O nome do pacote telegram-mcp no PyPI não é controlado por este projeto. Evite comandos de instalação telegram-mcp baseados em PyPI, a menos que a propriedade mude e o pacote seja verificado.
Este repositório inclui uma proteção de inicialização de melhor esforço que recusa distribuições telegram-mcp instaladas sem um checkout de fonte ou registro de instalação direto via git/arquivo. Essa proteção não pode ser executada quando o pacote PyPI não relacionado é iniciado, então use instalações baseadas em clone ou git explícito.
Prefira strings de sessão em vez de sessões de arquivo ao executar várias instâncias do servidor.
Por padrão, as chamadas da API do Telegram vão diretamente da sua máquina/contêiner para o Telegram. Se TELEGRAM_PROXY_* estiver configurado, o tráfego do Telegram é roteado através do proxy SOCKS/HTTP/MTProxy configurado.
O conteúdo gerado pelo usuário do Telegram é sanitizado antes de ser retornado aos clientes MCP.

Proteção contra Injeção de Prompt

Mensagens do Telegram, nomes de exibição, títulos de chat e rótulos de botões são conteúdo não confiável. O servidor mitiga o risco de injeção de prompt com:

Saída JSON estruturada para dados controlados pelo usuário quando prático.
sanitize_user_content(), sanitize_name() e sanitize_dict() para remoção de caracteres de controle, remoção de caracteres invisíveis e limites de comprimento.
Anotações de conteúdo MCP marcando o conteúdo retornado como dados de audiência do usuário.
Descrições de ferramentas que avisam os clientes para não tratar campos do Telegram retornados como instruções de modelo.
Sem filtragem frágil baseada em palavras-chave.

Solução de Problemas

Nenhuma sessão do Telegram configurada: defina TELEGRAM_SESSION_STRING, TELEGRAM_SESSION_NAME ou variantes multi-conta com sufixo.
Sessão não autorizada: execute uv run session_string_generator.py --qr fora do servidor MCP quando você puder escanear a partir de um aplicativo Telegram existente, ou uv run session_string_generator.py --phone quando precisar de login por código de telefone. Em seguida, defina TELEGRAM_SESSION_STRING em .env. O servidor MCP não realiza login interativo por código de telefone via stdio.
Credenciais de API inválidas: verifique TELEGRAM_API_ID e TELEGRAM_API_HASH em my.telegram.org/apps.
Banco de dados bloqueado: prefira strings de sessão ou certifique-se de que nenhum outro processo esteja usando a mesma sessão de arquivo.
Ferramentas de arquivo desabilitadas: passe raízes permitidas ou configure Raízes MCP no seu cliente.
Caminho rejeitado: garanta que o caminho esteja dentro de uma raiz permitida e não use padrões de travessia ou curinga.
Erros de autenticação após mudanças de senha: regenere sua string de sessão.
Ferramenta somente bot rejeitada: contas de usuário regulares não podem gerenciar configurações de comandos de bot.
Precisa de detalhes: verifique os logs do seu cliente MCP, saída do terminal e mcp_errors.log.

Contribuindo

Faça um fork e clone o repositório.
Instale dependências e hooks de git:
- uv sync
- uv run pre-commit install --hook-type pre-commit --hook-type pre-push
Crie um branch focado.
Adicione ou atualize testes quando o comportamento mudar.
Execute verificações localmente:
- uv run pre-commit run --all-files
- uv run pre-commit run --hook-stage pre-push --all-files
Abra um pull request com uma descrição concisa.

Licença

Este projeto é licenciado sob a Licença Apache 2.0.

Agradecimentos

Mantido por @chigwell e @l1v0n1. PRs são bem-vindos.