MCP 服务器

claude-code-telegrammer

Enables Claude Code to act as an autonomous Telegram agent with tools for replying, reacting, editing messages, searching history, and handling attachments. Includes a TUI watchdog for unattended operation.

README

claude-code-telegrammer

<p align="center"><b>Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent</b></p>

<p align="center"> <a href="https://claude-code-telegrammer.readthedocs.io/">Documentation</a> · <code>pip install claude-code-telegrammer</code> </p>

Problem and Solution

<table> <tr> <th align="center">#</th> <th>Problem</th> <th>Solution</th> </tr> <tr valign="top"> <td align="center">1</td> <td><h4>Hardcoded paths</h4>The official plugin hardcodes <code>~/.claude/</code> as its state directory (<a href="https://github.com/anthropics/claude-code/issues/851">#851</a>), making it impossible to run multiple bots or customize where access.json lives.</td> <td><h4>Configurable state directory</h4>All state (DB, lock, access config) lives under <code>CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR</code>. Run as many bots as you want, each with its own isolated state.</td> </tr> <tr valign="top"> <td align="center">2</td> <td><h4>409 Conflict crashes</h4>No single-instance guard — multiple sessions polling the same bot get 409 errors and crash each other (<a href="https://github.com/anthropics/claude-code/issues/1075">#1075</a>).</td> <td><h4>PID-based lock</h4>Automatic single-instance enforcement via PID lock file. Second instance detects the conflict and waits instead of crashing.</td> </tr> <tr valign="top"> <td align="center">3</td> <td><h4>Zombie CPU consumption</h4>After session ends, the plugin process lingers at 100% CPU — requires manual kill (<a href="https://github.com/anthropics/claude-code/issues/1146">#1146</a>).</td> <td><h4>Clean shutdown</h4>Exits gracefully on stdin close, SIGTERM, or SIGINT. No zombies, no manual cleanup.</td> </tr> <tr valign="top"> <td align="center">4</td> <td><h4>Only 3 basic tools</h4>The official plugin provides just send, get_updates, and set_reaction — no history, no search, no file handling, no message editing.</td> <td><h4>10 MCP tools</h4>reply, react, edit_message, get_history, get_unread, mark_read, download_attachment, send_document, search_messages, get_context — everything an autonomous agent needs.</td> </tr> <tr valign="top"> <td align="center">5</td> <td><h4>No message persistence</h4>Messages vanish after delivery. No way to search past conversations, track read status, or build context from history.</td> <td><h4>SQLite message store</h4>All messages persisted in WAL-mode SQLite with full-text search, reply threading (reply_to_message_id), read/replied tracking, and attachment metadata.</td> </tr> <tr valign="top"> <td align="center">6</td> <td><h4>No access control for groups</h4>Basic allowlist only — no per-group policies, no hot-reload when config changes.</td> <td><h4>DM + group policies</h4>Allowlist-based access control with separate DM and group chat policies via <code>access.json</code>, hot-reloaded on file change (mtime-based).</td> </tr> <tr valign="top"> <td align="center">7</td> <td><h4>No attachment support</h4>Cannot download inbound files or upload documents to chats.</td> <td><h4>Full attachment handling</h4>Inbound photos, documents, voice, audio, and video are auto-downloaded. Upload local files via <code>send_document</code> tool.</td> </tr> <tr valign="top"> <td align="center">8</td> <td><h4>Sessions stall unattended</h4>Claude Code halts at permission prompts or idle states with no way to recover — the agent just stops working.</td> <td><h4>TUI Watchdog</h4>Polls GNU Screen buffer, detects TUI state via pattern matching, sends keystrokes to auto-accept prompts and re-engage on idle. Throttled with burst limits.</td> </tr> </table>

<p align="center"><sub><b>Table 1.</b> Eight issues with the official Telegram plugin (as of April 2026) and how claude-code-telegrammer addresses each. These problems make the official plugin unusable for production autonomous agents.</sub></p>

Architecture

Custom Telegram MCP Server (ts/) -- Self-contained Bun + MCP server. 10 tools, SQLite persistence, allowlist access control, attachment handling, reaction support. Incoming messages acknowledged with 📩. Built-in responsiveness policy directs the agent to reply immediately and delegate heavy work to background subagents.
TUI Watchdog (lib/) -- Polls a GNU Screen session, detects Claude Code's TUI state via pattern matching, and sends keystrokes to keep the agent running unattended (auto-accepts permission prompts, re-engages on idle). Throttled with burst limits to prevent runaway responses. Orchestration handled by scitex-agent-container.

<details> <summary><strong>MCP Tools (10)</strong></summary>

Tool	Description
`reply`	Reply on Telegram. Supports threading (`reply_to`), auto-marks inbound as read. Inbound reply-to-message references are tracked and forwarded.
`react`	Add an emoji reaction to a message. Inbound reactions (`message_reaction`) are also delivered as channel notifications.
`edit_message`	Edit a previously sent bot message.
`get_history`	Retrieve message history for a chat from local SQLite.
`get_unread`	List unread inbound messages, optionally filtered by `chat_id`.
`mark_read`	Mark messages as read by `chat_id` or `message_ids`.
`download_attachment`	Download a Telegram file by `file_id`, returns local path.
`send_document`	Upload a local file to a Telegram chat.
`search_messages`	Text search across stored messages.
`get_context`	Recent conversation formatted as compact text for LLM context.

</details>

Important: Bot Token Exclusivity

This MCP server must be the sole consumer of its configured Telegram bot token. The Telegram Bot API allows only one getUpdates long-polling connection per token.

What happens with duplicate consumers:

Scenario	Symptom	Detection
Two pollers start simultaneously	One gets 409, the other wins silently	The loser sees `409 Conflict` in logs
Two pollers start sequentially	Both appear to work, but only one receives messages	No error — the other poller gets empty responses forever
Webhook active + poller	Poller gets nothing	No error — Telegram ignores `getUpdates` when webhook is set

Why 409 detection alone is insufficient: The Telegram API does not reliably return 409 for all conflict cases. When two consumers poll sequentially (not overlapping), both connections succeed — one simply receives all messages while the other gets none, with no error. The server performs a timeout=3 preflight check at startup to catch overlapping polls, but this cannot detect the sequential case.

If messages aren't arriving:

Check if another process is polling the same token: ps aux | grep telegram-server
Check if a webhook is set: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo
Use a separate bot token per component (recommended)
Or disable the other consumer

Alternative: Webhook mode via scitex-orochi. If you run scitex-orochi, it supports Telegram webhook mode (POST /webhook/telegram/) which eliminates polling conflicts entirely. Telegram pushes updates to a single HTTPS endpoint instead of competing pollers. See SCITEX_OROCHI_TELEGRAM_WEBHOOK_URL in the orochi documentation.

Installation

Prerequisites

Bun >= 1.0 (for the MCP server)
GNU Screen (for watchdog, optional)

Install

git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
cd claude-code-telegrammer/ts && bun install

Quickstart

Get a Telegram Bot Token

Open Telegram and message @BotFather
Send /newbot, then enter a name (e.g., Claude Code Telegrammer) and a username (e.g., ClaudeCodeTelegrammerBot)
BotFather replies with your token: 123456789:AAH...

Verify your token works:

curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
# Should return {"ok":true,"result":{"is_bot":true,...}}

Open your bot (e.g., t.me/ClaudeCodeTelegrammerBot) and send any message to start a conversation

Register MCP Server with Claude Code

Copy the example and fill in your values (.mcp.json is gitignored):

{
  "mcpServers": {
    "claude-code-telegrammer": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/claude-code-telegrammer/ts/telegram-server.ts"],
      "env": {
        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN": "123456789:AAH...",
        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS": "YOUR_TELEGRAM_USER_ID",
        "CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR": "~/.claude-code-telegrammer"
      }
    }
  }
}

cp .mcp.json.example .mcp.json
# Edit .mcp.json with your token, user ID, and paths

Find your Telegram user ID by messaging @userinfobot.

Run

claude \
    --dangerously-skip-permissions \
    --dangerously-load-development-channels server:claude-code-telegrammer

You should see Listening for channel messages from: server:claude-code-telegrammer in the Claude Code TUI. Send a message from Telegram to your bot — Claude Code will receive it as a channel notification.

Interfaces

<details> <summary><strong>MCP Server -- for AI Agents</strong></summary>

Start command:

bun run ts/telegram-server.ts

10 tools exposed via MCP stdio protocol. See MCP Tools above. The server's MCP instructions include a responsiveness policy that directs the agent to acknowledge messages immediately and delegate heavy work to background subagents.

</details>

<details> <summary><strong>Skills -- for AI Agent Discovery</strong></summary>

Skills are bundled at src/claude_code_telegrammer/_skills/claude-code-telegrammer/SKILL.md.

</details>

Architecture

User (Telegram)
    |
    |  Bot API (getUpdates long-polling)
    v
┌──────────────────────────────────────────────────────────────┐
│  Custom Telegram MCP Server (ts/telegram-server.ts)          │
│    Bun + @modelcontextprotocol/sdk                           │
│                                                              │
│    ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌────────────┐    │
│    │ Poller  │  │  Store  │  │  Tools   │  │ Attachments│    │
│    │ (long   │  │ (SQLite │  │ (10 MCP  │  │ (download  │    │
│    │  poll)  │  │  WAL)   │  │  tools)  │  │  queue)    │    │
│    └─────────┘  └─────────┘  └──────────┘  └────────────┘    │
│    ┌─────────┐  ┌─────────┐  ┌──────────┐                    │
│    │ Access  │  │  Config │  │   Lock   │                    │
│    │ (allow- │  │ (env    │  │ (PID     │                    │
│    │  list)  │  │  vars)  │  │  file)   │                    │
│    └─────────┘  └─────────┘  └──────────┘                    │
└──────────────────────┬───────────────────────────────────────┘
                       │ MCP stdio
                       v
┌──────────────────────────────────────────────────────────────┐
│  Claude Code (in GNU Screen session)                         │
│    --mcp-config points to the custom MCP server              │
└──────────────────────┬───────────────────────────────────────┘
                       │ screen buffer
                       v
┌──────────────────────────────────────────────────────────────┐
│  Watchdog (claude-code-telegrammer-watchdog)                 │
│    Polls screen buffer every 1.5s                            │
│    Detects: y/n prompt -> "1", y/y/n -> "2", idle -> cmd     │
│    Throttled: burst limit, same-state delay, min interval    │
└──────────────────────────────────────────────────────────────┘

<details> <summary><strong>State Detection</strong></summary>

State	Pattern	Response
`running`	`(esc to interrupt)`, `tokens ·`, `ing...`	No action
`y_n`	`1. Yes` + `3. No` (two-choice prompt)	Send `1` (accept)
`y_y_n`	`2. Yes, and...` / `2. Yes, allow...` / `2. Yes, don't ask...`	Send `2` (accept all)
`waiting`	Cooking puns (`Crafted for`, etc.), empty `>` prompt, idle hints	Send configurable command

Response throttling: minimum interval between responses, burst limit (10 in 3s window), same-state delay.

</details>

<details> <summary><strong>Configuration (Environment Variables)</strong></summary>

MCP Server:

Variable	Required	Default	Description
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_BOT_TOKEN`	Yes	--	Telegram Bot API token
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR`	No	`~/.claude-code-telegrammer`	Directory for SQLite DB, access.json, lock file
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS`	No	--	Comma-separated Telegram user IDs for DM allowlist
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_HOST_NAME`	No	`os.hostname()`	Hostname stored with each message
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_PROJECT`	No	`process.cwd()`	Project path stored with each message
`CLAUDE_CODE_TELEGRAMMER_TELEGRAM_AGENT_ID`	No	`'telegram'`	Agent identifier stored with each message

Watchdog:

Variable	Default	Description
`CLAUDE_CODE_TELEGRAMMER_SESSION`	`claude-code-telegrammer`	GNU Screen session name
`CLAUDE_CODE_TELEGRAMMER_WATCHDOG_INTERVAL`	`1.5`	Poll interval in seconds
`CLAUDE_CODE_TELEGRAMMER_RESP_Y_N`	`1`	Response for y/n prompts
`CLAUDE_CODE_TELEGRAMMER_RESP_Y_Y_N`	`2`	Response for y/y/n prompts
`CLAUDE_CODE_TELEGRAMMER_RESP_WAITING`	`/speak-and-call`	Response when idle/waiting

</details>

<details> <summary><strong>SQLite Schema (v2)</strong></summary>

All messages persisted in $CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR/messages.db using WAL mode.

messages table: direction, chat_id, message_id, user_id, username, text, timestamps (telegram_ts, received_at, read_at, replied_at), threading (reply_to_message_id, reply_to_row_id), identity (host, project, agent_id, bot_token_hash), raw_json.

attachments table: message_row_id (FK), kind, file_id, file_name, mime_type, file_size, local_path, downloaded_at.

meta table: key-value store for schema_version, update_offset.

</details>

<details> <summary><strong>Integration with scitex-agent-container</strong></summary>

For YAML-based agent orchestration (screen sessions, watchdog lifecycle, restart policies), see scitex-agent-container.

</details>

<details> <summary><strong>Access Control</strong></summary>

Managed via access.json in $CLAUDE_CODE_TELEGRAMMER_TELEGRAM_STATE_DIR:

{
  "dmPolicy": "allowlist",
  "allowFrom": ["123456789"],
  "groups": {
    "-100123456": {
      "requireMention": true,
      "allowFrom": ["123456789"]
    }
  }
}

Merged with CLAUDE_CODE_TELEGRAMMER_TELEGRAM_ALLOWED_USERS env var at runtime. Mtime-based caching means edits take effect without restart.

</details>

Part of SciTeX

claude-code-telegrammer is part of SciTeX. It provides the Telegram communication layer and TUI watchdog used by scitex-agent-container for autonomous agent operation.

┌─────────────────────────────────────────────────────────┐
│ scitex-orochi         — agent definitions, dashboard    │
└──────────────────────────┬──────────────────────────────┘
                           v
┌─────────────────────────────────────────────────────────┐
│ scitex-agent-container  — lifecycle, health, restart    │
└──────────────────────────┬──────────────────────────────┘
                           v
┌─────────────────────────────────────────────────────────┐
│ claude-code-telegrammer  <-- YOU ARE HERE               │
│   MCP server: Telegram API, message DB, 10 tools        │
│   Watchdog: TUI auto-response, screen polling           │
└─────────────────────────────────────────────────────────┘

References

Claude Code Channels -- Official documentation for Claude Code's channel system
Official Telegram Plugin -- The plugin:telegram@claude-plugins-official source code
#851: STATE_DIR not respected -- Hardcoded access.json path
#1075: 409 Conflict errors -- Multiple instances polling the same bot
#1146: Zombie CPU consumption -- Runaway process after session ends
Telegram BotFather -- Create and manage Telegram bots
Telegram Bot API -- Official Bot API documentation
MCP Specification -- Model Context Protocol standard
claude-code-telegrammer Issues -- Bug reports and feature requests
claude-code-telegrammer Pull Requests -- Contributions

Four Freedoms for Research

The freedom to run your research anywhere -- your machine, your terms.

The freedom to study how every step works -- from raw data to final manuscript.

The freedom to redistribute your workflows, not just your papers.

The freedom to modify any module and share improvements with the community.

AGPL-3.0 -- because we believe research infrastructure deserves the same freedoms as the software it runs on.

claude-code-telegrammer

README

claude-code-telegrammer

Problem and Solution

Architecture

Important: Bot Token Exclusivity

Installation

Prerequisites

Install

Quickstart

Get a Telegram Bot Token

Register MCP Server with Claude Code

Run

Interfaces

Architecture

Part of SciTeX

References

推荐服务器