MCP Telegram

Servidor MCP do Telegram com 20 ferramentas — ler chats, pesquisar mensagens, baixar mídia via MTProto

Documentação

Servidor MCP Telegram

📖 Documentação · ☁️ Versão em nuvem — conecte o Telegram ao Claude.ai ou ChatGPT em 30 segundos com código QR, sem necessidade de chaves de API.

Servidor MCP Telegram — um servidor de Protocolo de Contexto de Modelo (MCP) que conecta assistentes de IA como Claude e ChatGPT ao Telegram via protocolo MTProto. Diferente de bots, ele opera como um userbot — funciona sob sua conta pessoal do Telegram usando GramJS, dando acesso total aos seus chats, contatos e histórico de mensagens.

Recursos

Cobertura abrangente de ferramentas — o servidor MCP Telegram mais completo disponível
Protocolo MTProto — acesso direto à API do Telegram, não a API limitada de bots
Userbot — opera como sua conta pessoal, não como um bot
Completo — mensagens, reações, enquetes, mensagens agendadas, figurinhas, mídia, contatos e muito mais
Tópicos de fórum — liste tópicos, leia mensagens por tópico, envie para tópicos específicos, contagem de não lidos por tópico
Figurinhas — pesquise conjuntos de figurinhas, navegue por figurinhas instaladas/recentes, envie figurinhas para qualquer chat
Gerenciamento de conta e perfil — atualize perfil, defina status de emoji, aniversário, canal pessoal, foto de perfil, gerencie configurações de privacidade, sessões, temporizadores de exclusão automática
Pastas de chat — crie, edite, exclua e reordene pastas, alterne etiquetas de pastas, leia pastas sugeridas (v1.33.0)
Privacidade global — leia e defina configurações de privacidade em toda a conta (v1.33.0)
Pesquisa global — pesquise mensagens em todos os chats de uma vez
Polling em tempo real — obtenha atualizações via cursores sem estado; o agente possui o estado {pts, qts, date}
Bots inline e botões — consulte bots inline, envie resultados, pressione botões de callback
Stories — leia stories de contatos, obtenha estatísticas de visualização; publique/edite/exclua stories, reaja, fixe, modo invisível, arquive, denuncie (v1.30.0)
Discussão — obtenha informações do grupo de discussão para posts de canal com comentários, liste grupos elegíveis para discussão (v1.30.0)
Confirmações de leitura — quem leu uma mensagem em um grupo pequeno, quando sua mensagem privada foi lida (v1.30.0)
Controles de administrador — alterne assinaturas de canal, anti-spam, modo fórum, pré-história; aprove solicitações de entrada
Estatísticas — análises de canal e supergrupo (GetBroadcastStats / GetMegagroupStats)
Boosts e Negócios — status de boost, lista de boosters, CRUD de links de negócios do Telegram, horário de trabalho, localização, mensagens de saudação/ausência/introdução
Presentes com estrela — navegue por presentes disponíveis e salvos, salve/converta presentes, gerencie saldo e assinaturas de Stars (opt-in via MCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
Daemon compartilhado — um processo em segundo plano atende vários clientes MCP em uma única sessão do Telegram; veja o guia de daemon compartilhado (v1.38.0)
Login com código QR — autentique-se escaneando um código QR no aplicativo Telegram
Persistência de sessão — faça login uma vez, permaneça conectado entre reinicializações
Saída legível — nomes de remetentes são resolvidos, não apenas IDs numéricos
Funciona com qualquer cliente MCP — Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra, etc.

Pré-requisitos

Node.js 18 ou superior
Credenciais da API do Telegram — API_ID e API_HASH de my.telegram.org

Início Rápido

1. Obtenha as credenciais da API do Telegram

Acesse my.telegram.org e faça login com seu número de telefone.
Navegue até Ferramentas de desenvolvimento de API.
Crie um novo aplicativo (qualquer nome e plataforma).
Copie o App api_id e o App api_hash.

2. Login

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login

Um código QR aparecerá no terminal. Abra o Telegram no seu celular, vá em Configurações > Dispositivos > Vincular dispositivo de desktop e escaneie o código. A sessão é salva em ~/.mcp-telegram/session e reutilizada automaticamente.

Caminho personalizado da sessão: defina TELEGRAM_SESSION_PATH=/path/to/session para armazenar o arquivo de sessão em outro local.

Verificação em duas etapas (2FA): se sua conta tiver uma senha de nuvem habilitada, escanear o código QR não é suficiente — o Telegram também exige a senha. Forneça-a via TELEGRAM_2FA_PASSWORD para que o login possa ser concluído:
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login
A senha é usada apenas localmente para responder ao desafio SRP do Telegram e nunca é persistida.

3. Adicionar ao Claude

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

É isso! Peça ao Claude para executar telegram-status para verificar.

Múltiplas Contas

Use TELEGRAM_SESSION_PATH para executar contas separadas do Telegram lado a lado:

# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login

Depois adicione cada uma como um servidor MCP separado:

claude mcp add telegram-work -s user \
  -e TELEGRAM_API_ID=ID1 \
  -e TELEGRAM_API_HASH=HASH1 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
  -- npx @overpod/mcp-telegram

claude mcp add telegram-personal -s user \
  -e TELEGRAM_API_ID=ID2 \
  -e TELEGRAM_API_HASH=HASH2 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
  -- npx @overpod/mcp-telegram

Cada conta tem seu próprio arquivo de sessão — sem conflitos.

Múltiplos agentes / clientes concorrentes (daemon compartilhado)

O oposto de múltiplas contas: uma conta dirigida por muitos clientes ao mesmo tempo — várias janelas do Claude Code, subagentes paralelos ou múltiplos IDEs. Normalmente cada processo abre a mesma sessão e eles se expulsam mutuamente com AUTH_KEY_DUPLICATED. O modo de serviço resolve isso.

Execute um daemon persistente único que possui a única conexão do Telegram. Todos os outros processos detectam automaticamente o daemon (via um bloqueio de PID) e se tornam clientes leves que fazem proxy de chamadas de ferramentas para ele via um socket Unix local:

# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)

Depois aponte cada cliente MCP para a mesma instalação com o mesmo TELEGRAM_SESSION_PATH — sem argumento serve. Eles se conectam ao daemon automaticamente; fechar qualquer cliente nunca derruba a conexão compartilhada. As credenciais são exigidas apenas pelo daemon (o proprietário), então os comandos do cliente podem omitir TELEGRAM_API_ID/TELEGRAM_API_HASH e mantê-las onde o daemon é executado.

Veja o guia de daemon compartilhado para uma unidade systemd e uso via SSH.

Suporte a Proxy

Se o Telegram estiver bloqueado ou você estiver executando em um ambiente containerizado (Docker, K3s), use um SOCKS5 ou MTProxy:

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram

Variável	Descrição
`TELEGRAM_PROXY_IP`	Endereço do servidor proxy
`TELEGRAM_PROXY_PORT`	Porta do servidor proxy
`TELEGRAM_PROXY_SOCKS_TYPE`	`4` ou `5` (padrão: `5`)
`TELEGRAM_PROXY_SECRET`	Segredo do MTProxy (habilita o modo MTProxy)
`TELEGRAM_PROXY_USERNAME`	Autenticação opcional do proxy
`TELEGRAM_PROXY_PASSWORD`	Autenticação opcional do proxy

Conexão via WSS (porta 443)

Se o IP do seu VPS ou hospedagem for acessível na porta de saída 443 mas não na porta padrão do MTProto 80 (alguns provedores de nuvem bloqueiam a porta 80 nos intervalos de IP dos DCs do Telegram como política anti-abuso), defina:

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

Variável	Descrição
`TELEGRAM_USE_WSS`	Quando `true`, o gramJS usa a porta `443` em vez de `80` para o transporte TCPFull do MTProto. Padrão: `false`. Não pode ser combinado com `TELEGRAM_PROXY_*` (limitação do gramJS) — se ambos forem definidos, `useWSS` é ignorado e o proxy tem precedência (um aviso é registrado).

Opções de Instalação

npx (recomendado, zero instalação)

Não é necessário clonar ou instalar nada. Basta usar npx @overpod/mcp-telegram.

Instalação global

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

Binário pré-compilado (sem necessidade de runtime)

Baixe de Releases — binários autônomos de arquivo único, zero dependências:

Plataforma	Servidor	CLI de Login
Linux x64	`mcp-telegram-linux-x64`	`mcp-telegram-login-linux-x64`
Linux ARM64	`mcp-telegram-linux-arm64`	`mcp-telegram-login-linux-arm64`
macOS x64	`mcp-telegram-darwin-x64`	`mcp-telegram-login-darwin-x64`
macOS ARM64	`mcp-telegram-darwin-arm64`	`mcp-telegram-login-darwin-arm64`
Windows x64	`mcp-telegram-windows-x64.exe`	`mcp-telegram-login-windows-x64.exe`

# Download (example for Linux x64)
curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login

# Run
./mcp-telegram

A partir do código-fonte

git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build

Docker

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

Execute o servidor MCP:

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

Nota: O login deve ser feito uma vez via terminal. Depois disso, a sessão é persistida em ~/.mcp-telegram e reutilizada automaticamente.

Uso com Clientes MCP

Claude Code (CLI)

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Claude Desktop

Abra seu arquivo de configuração:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione o servidor Telegram:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["@overpod/mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Reinicie o Claude Desktop.
Peça ao Claude: "Execute telegram-login" — um código QR aparecerá. Se a imagem não estiver visível, ela também é salva em ~/.mcp-telegram/qr-login.png. Escaneie-a no Telegram (Configurações > Dispositivos > Vincular dispositivo de desktop).
Peça ao Claude: "Execute telegram-status" para verificar a conexão.

Nota: Nenhum terminal é necessário! O login funciona inteiramente pelo Claude Desktop.

Claude Desktop (Binário)

Mesma configuração, mas usando o binário pré-compilado em vez de npx:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Claude Desktop (Docker)

Faça login via terminal primeiro (veja a seção Docker acima).
Adicione ao seu arquivo de configuração:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_API_ID=YOUR_ID",
        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
        "mcp-telegram"
      ]
    }
  }
}

Reinicie o Claude Desktop. Peça ao Claude: "Execute telegram-status" para verificar.

Cursor / VS Code

Adicione a mesma configuração JSON acima às suas configurações de MCP (Cursor Settings > MCP, ou configuração MCP do VS Code).

Mastra

import { MCPClient } from "@mastra/mcp";

const telegramMcp = new MCPClient({
  id: "telegram-mcp",
  servers: {
    telegram: {
      command: "npx",
      args: ["@overpod/mcp-telegram"],
      env: {
        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
      },
    },
  },
});

Ferramentas

Todas as ferramentas são auto-descobríveis via MCP — seu cliente de IA verá a lista completa com parâmetros e descrições quando conectado.

Categoria	Ferramentas
Autenticação	`telegram-status`, `telegram-login`, `telegram-logout`
Mensagens	`telegram-send-message` (incluindo `quoteText` para citações de resposta verbatim e mensagem Premium `effect`), `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link`
Agendados	`telegram-get-scheduled`, `telegram-delete-scheduled`
Leitura	`telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs`
Rascunhos	`telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts`
Tópicos do fórum	`telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic`
Enquetes	`telegram-create-poll`
Interação com Enquetes (v1.31.0)	`telegram-vote-poll`, `telegram-get-poll-results`, `telegram-get-poll-voters`, `telegram-close-poll`
Reações	`telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions`
Reações pagas (v1.31.0)	`telegram-send-paid-reaction` (★ Stars), `telegram-toggle-paid-reaction-privacy`, `telegram-get-paid-reaction-privacy`
Transcrição de áudio (v1.31.0)	`telegram-transcribe-audio` (Premium), `telegram-get-transcription`, `telegram-rate-transcription`
Verificação de fatos (v1.31.0)	`telegram-get-fact-check`, `telegram-edit-fact-check`, `telegram-delete-fact-check`
Adesivos	`telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets`
Mídia	`telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview`
Envio de mídia rica	`telegram-send-voice`, `telegram-send-video-note` (vídeo redondo), `telegram-send-location` (estático ou ao vivo), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 fotos/vídeos agrupados)
Grupos	`telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log`
Informações do chat	`telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders`
Pastas (v1.33.0)	`telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags`
Privacidade global (v1.33.0)	`telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings`
Links de convite	`telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link`
Contatos	`telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests`
Moderação	`telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam`
Perfis (leitura)	`telegram-get-profile`, `telegram-update-profile`
Perfil (escrita, v1.32.0)	`telegram-set-emoji-status` (Premium), `telegram-list-emoji-statuses`, `telegram-clear-recent-emoji-statuses`, `telegram-set-profile-color` (Premium), `telegram-set-birthday`, `telegram-set-personal-channel`, `telegram-set-profile-photo`, `telegram-delete-profile-photo`
Conta	`telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete`
Fixação	`telegram-pin-message`, `telegram-unpin-message`
Configurações do chat	`telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread`
Alternâncias de administrador	`telegram-toggle-channel-signatures`, `telegram-toggle-anti-spam`, `telegram-toggle-forum-mode`, `telegram-toggle-prehistory-hidden`, `telegram-set-chat-reactions`, `telegram-approve-join-request`
Estatísticas	`telegram-get-broadcast-stats`, `telegram-get-megagroup-stats`
Bots inline e botões	`telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons`
Polling em tempo real	`telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates`
Stories (leitura)	`telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views`
Stories (escrita, v1.30.0)	`telegram-send-story`, `telegram-edit-story`, `telegram-delete-stories`, `telegram-react-to-story`, `telegram-export-story-link`, `telegram-read-stories`, `telegram-toggle-story-pinned`, `telegram-toggle-story-pinned-to-top`, `telegram-activate-stealth-mode` (Premium), `telegram-get-stories-archive`, `telegram-report-story`
Discussão (v1.30.0)	`telegram-get-discussion-message`, `telegram-get-groups-for-discussion`
Confirmações de leitura (v1.30.0)	`telegram-get-message-read-participants`, `telegram-get-outbox-read-date`
Impulsos	`telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list`
Negócios (v1.32.0)	`telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro`
Opt-in (controlado por variável de ambiente)	`telegram-get-group-call`, `telegram-get-group-call-participants` (requer `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars e presentes `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (requer `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requer `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`)

Dica: Pergunte ao seu assistente de IA "Quais ferramentas do Telegram estão disponíveis?" para obter a lista completa com parâmetros e descrições.

Recursos Opcionais

Algumas ferramentas estão desabilitadas por padrão e devem ser ativadas via variáveis de ambiente:

Variável	Valor	Ferramentas habilitadas
`MCP_TELEGRAM_ENABLE_GROUP_CALLS`	`1`	`telegram-get-group-call`, `telegram-get-group-call-participants`
`MCP_TELEGRAM_ENABLE_STARS`	`1`	Saldo de Stars e transações, opções de recarga, assinaturas e Presentes com Star (navegar / salvar / converter)
`MCP_TELEGRAM_ENABLE_QUICK_REPLIES`	`1`	`telegram-get-quick-replies`, `telegram-get-quick-reply-messages`

Adicione-os ao seu arquivo .env ou à configuração do cliente MCP para ativá-los.

Desenvolvimento

npm run dev        # Start with file watching (tsx)
npm start          # Start the MCP server
npm run login      # QR code login in terminal
npm run build      # Compile TypeScript
npm run lint       # Check code with Biome
npm run lint:fix   # Auto-fix lint issues
npm run format     # Format code with Biome

Estrutura do Projeto

src/
  index.ts            -- MCP server entry point
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login
  tools/              -- Modular tool definitions
    auth.ts           -- Connection & login
    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
    chats.ts          -- Chat listing, group management, admin toggles, stats
    contacts.ts       -- Contacts, profiles, moderation
    media.ts          -- Files, photos, downloads
    reactions.ts      -- Reactions, set-chat-reactions
    extras.ts         -- Pin, schedule, polls, topics
    stickers.ts       -- Sticker sets, send, search, browse
    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
    boosts.ts         -- Boost status, my boosts, boosters list
    stories.ts        -- Stories: list all, peer, by-id, view stats
    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
    shared.ts         -- Shared utilities

Stack Tecnológico

TypeScript -- ES2022, módulos ESM
GramJS (telegram) -- Cliente Telegram MTProto
@modelcontextprotocol/sdk -- Estrutura do servidor MCP
Zod -- Validação de esquema em tempo de execução para parâmetros de ferramentas
Biome -- Linter e formatador
tsx -- Execução de TypeScript sem etapa de build
dotenv -- Gerenciamento de variáveis de ambiente

Solução de Problemas

AUTH_KEY_DUPLICATED

Uma sessão do Telegram só pode ser usada por um processo por vez. Se você receber AUTH_KEY_DUPLICATED, significa que outro processo já está usando o mesmo arquivo de sessão.

Solução: Crie sessões separadas para cada ambiente:

# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login

# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login

Depois defina TELEGRAM_SESSION_PATH na configuração MCP de cada ambiente de acordo.

Segurança

As credenciais da API são armazenadas em .env (ignorado pelo git)
A sessão é armazenada em ~/.mcp-telegram/session com permissões 0600 (acesso somente do proprietário)
O diretório da sessão é criado com permissões 0700
O número de telefone não é necessário -- autenticação apenas por QR
Nenhum dado é enviado a serviços terceiros -- toda comunicação vai diretamente aos servidores do Telegram via MTProto
Os códigos de login por QR são gerados localmente e nunca saem da sua máquina
Uma sessão por processo -- usar a mesma sessão em múltiplos processos simultaneamente causa erros AUTH_KEY_DUPLICATED (veja Solução de Problemas)
Este é um userbot (conta pessoal), não um bot -- respeite os Termos de Serviço do Telegram

Licença

MIT