Telegram channel for Claude Code. Self-contained MCP server with full access control: pairing, allowlists, group support with mention-triggering. State lives in ~/.claude/channels/telegram/access.json — managed by the /telegram:access skill. Telegram's Bot API has no history or search. Reply-only tools.
This server implements 10 Telegram-focused tools with schemas and descriptions present in source, but exhibits significant quality gaps that prevent production recommendation. Naming is generally action-verb based and clear. Descriptions exist but are inconsistent in depth and quality (ranging 20 - 180 chars, well below the 50 - 200 char LLM-optimized baseline). Input schemas are present for all tools but lack proper typing on several parameters (chat_id and user_id are strings without format constraints; emoji, voice_id lack enums or validation guidance). Output schemas are entirely undocumented, LLMs cannot predict return structure. Error handling is minimal; recovery guidance absent. Security concerns include plaintext environment variable injection, no audit logging, and no permission gates on destructive operations (telegram_shell_run executes arbitrary shell commands with zero validation). Tool composition is reasonable, but several tools conflate concerns (e.g., telegram_telegraph_publish handles both content publishing AND token creation in a single tool). Parameter dependencies are undocumented (e.g., voice_id default behavior, allowed_reactions constraint). The server demonstrates competent implementation but lacks the rigor expected of production-grade agent tools.
Grant Telegram user or channel access to Claude via pair code.
Revoke Telegram user or channel access to Claude.
Request a full context reset by writing a restart signal for the supervisor, terminating the current Claude session.
Convert text to speech using ElevenLabs and send as voice message.
Append notes to long-term memory (stored in ~/.claude/channels/telegram/data/memory.md).
React to a message in Telegram with an emoji reaction.
Send a message to a Telegram channel or conversation via the telegram bot.
Arbitrary shell command execution with zero input validation or sanitization. telegram_shell_run accepts any command string and executes it with spawnSync/execSync. Vulnerable to command injection if called by a compromised or adversarial agent.
Destructive operations lack confirmation step or permission gate. telegram_access_revoke, telegram_context_reset, and telegram_shell_run can be invoked by any agent without a confirmation request or permission check. No dry-run variant. Agents in retry loops or compromised agents can cause irreversible damage.
No output schemas documented for any tool. LLMs cannot predict return structure, field names, or types. Agents must infer output format from description or fail on unexpected responses. This violates the pattern:tool-description and pattern:response-shaper patterns and wastes LLM reasoning tokens on parsing unstructured output.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 47 | 2026-07-28+ | v2 |
Execute shell commands with controlled output length (first 5KB returned).
Publish long-form Markdown content to Telegraph (telegra.ph) for Instant View in Telegram.
Transcribe voice/audio messages using Whisper API (OpenAI, Groq, or Deepgram).
Parameter descriptions are inconsistent in depth and detail. Some parameters (e.g., emoji in telegram_react) mention constraints (ALLOWED_REACTIONS) only in the tool description, not in the parameter description where LLMs will search for validation guidance. ALLOWED_REACTIONS set defined in code is invisible to the agent unless explicitly documented in parameter constraints.
No error handling or recovery guidance. Tools provide no indication of what errors are retryable, user-fixable, or fatal. For example, telegram_whisper_transcribe offers no guidance if the file_id is invalid or the audio format is unsupported. Agents cannot determine next steps.
Parameters accept opaque identifiers (chat_id, user_id) as strings with no format guidance or human-friendly alternatives. Agents must already know whether chat_id is a numeric Telegram ID, a @channel_name, or a channel name. No lookup tool (search_channels, resolve_user) exists to convert user-provided names to system IDs.
Tool composition issue: telegram_telegraph_publish conflates content publishing with token management. The tool must call ensureTelegraphToken() internally, creating and persisting a token on first use. This hidden side effect (writing to .env) is not documented and complicates retry semantics, a second call with the same input may succeed silently even if the token already exists.
No audit logging or permission gates. Destructive tools (access_grant, access_revoke, shell_run) do not log who called them, with which parameters, or when. No permission checks (e.g., verify caller is admin) before granting/revoking access. Compliance and incident response will be difficult.
telegram_react description mentions ALLOWED_REACTIONS set but does not provide an enum constraint in the parameter definition. LLMs cannot see the valid emoji set without reading the full tool description or source code. An enum constraint in the schema would be machine-parseable and prevent hallucinated emoji.
Missing batch or multi-tool operations. If an agent needs to send the same message to 10 channels, it must call telegram_send_message 10 times. A single batch_send_message tool accepting an array of chat_ids would reduce token overhead and latency.