Setup with agent

Better Telegram MCP — Agent Setup Guide

Give this file to your AI agent to automatically set up better-telegram-mcp.

2026-05-02 Update (v<auto>+): Plugin install (Option 1) uses stdio mode with TELEGRAM_BOT_TOKEN. Bot mode only. User mode (MTProto via phone+OTP) is HTTP-only after this update. Set TELEGRAM_BOT_TOKEN in plugin config (Option 1), or switch to HTTP mode for user mode.

Method overview

This plugin supports 3 install methods. Pick the one that matches your use case:

Priority	Method	Transport	Best for
1. Default	Plugin install (uvx/npx)	stdio	Quick local start, single workstation, no OAuth/HTTP needed.
2. Fallback	Docker stdio (docker run -i --rm)	stdio	Windows/macOS where native uvx/npx hits PATH or Python version issues.
3. Recommended	Docker HTTP (docker run -p 8080:8080)	HTTP	Multi-device, OAuth/relay-form auth, team self-host, claude.ai web compatibility.

All MCP servers across this stack share this priority hierarchy. Note: 2 plugins (better-godot-mcp and better-code-review-graph) only support Method 1 (stdio) — they need direct host access to project files / repo paths and don’t ship Docker / HTTP variants.

⚠️ Mutually exclusive — pick ONE per plugin: If you choose Method 2 (Docker stdio override) OR Method 3 (HTTP), do NOT also /plugin install this plugin via marketplace. Both load simultaneously and create duplicate entries in /mcp dialog (plugin’s stdio + your override). Plugin matching is by endpoint (URL or command string) per CC docs, not by name — and npx/uvx ≠ docker ≠ HTTP URL, so all three are distinct endpoints. Trade-off: choosing Method 2 or Method 3 means you lose this plugin’s skills/agents/hooks/commands. For full plugin features, use Method 1 (default plugin install) with userConfig credentials prompted at install time.

Option 1: Claude Code Plugin (Recommended, stdio Bot Mode Only)

Credential prompts at install

When you run /plugin install, Claude Code prompts you for the following credentials (declared in userConfig per CC docs). Sensitive values are stored in your system keychain and persist across /plugin update:

Field	Required	Where to obtain
TELEGRAM_BOT_TOKEN	Optional (required for stdio bot mode)	From @BotFather. Note: HTTP user-mode (phone+OTP) is configured via relay form at /authorize, not via plugin install prompt.

Steps

# Install from marketplace (includes skills: /setup-bot, /channel-post)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

Paste your bot token when prompted. Bot mode only — user mode (read messages, browse chats) requires HTTP (Option 3) and uses a separate auth flow (phone+OTP via web form, not userConfig).

Note: This installs the full plugin (skills + agents + hooks + commands + stdio MCP server). If you’d rather use Option 2 (Docker stdio) or Option 3 (HTTP) below, DO NOT /plugin install this plugin — pick Option 2 or Option 3 instead. All three methods are mutually exclusive (see Method overview).

Option 2: Docker stdio (fallback)

⚠️ Before adding the Docker stdio override below, ensure this plugin is NOT installed via marketplace: Run /plugin uninstall better-telegram-mcp@n24q02m-plugins first if you previously ran /plugin install. Otherwise both entries (plugin’s npx/uvx stdio + your docker run stdio) will load simultaneously since plugin matches by endpoint (command string), not by name.

Trade-off accepted: Choosing this method means you lose this plugin’s skills/agents/hooks/commands. Use Option 1 instead if you want full plugin features.

docker run -i --rm \
  -e TELEGRAM_BOT_TOKEN=your_bot_token \
  n24q02m/better-telegram-mcp

Or as an MCP server config:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_BOT_TOKEN",
        "n24q02m/better-telegram-mcp"
      ]
    }
  }
}

Docker stdio supports bot mode only. For user mode, run the container in HTTP mode (Option 3 self-host).

Why upgrade to HTTP mode?

Stdio (Options 1-2) is the simplest path for bot mode, but stdio cannot host the browser-based phone+OTP flow that user mode requires. Switch to HTTP for any of these reasons:

• User mode access (REQUIRED for user mode) — read messages, browse chat history, list contacts, create groups/channels. Bot tokens cannot do this; only MTProto user sessions can. User mode auth is browser-based (phone + OTP code from Telegram app + optional 2FA password) and only HTTP transport hosts that flow.
• claude.ai web compatibility — claude.ai supports HTTP MCP servers; stdio is desktop/CLI only.
• One server, many sessions — a single HTTP server is shared across N Claude Code sessions instead of one stdio process per session.
• Multi-device cred sync — log in once on any device; the server keeps the session.
• Multi-user team sharing — HTTP supports per-JWT-sub credential isolation, so a team can share one self-hosted instance.
• Always-on persistent process — enables webhook listeners, long-running agents, and scheduled tasks.

Option 3: Docker HTTP (recommended)

⚠️ Before adding the HTTP override below, ensure this plugin is NOT installed via marketplace: Run /plugin uninstall better-telegram-mcp@n24q02m-plugins first if you previously ran /plugin install. Otherwise both entries (plugin’s stdio + your HTTP override) will load simultaneously since plugin matches by endpoint, not name.

Trade-off accepted: Choosing this method means you lose this plugin’s skills/agents/hooks/commands. For example, the better-telegram-mcp:setup-bot skill will no longer be available. Use Option 1 instead if you want full plugin features.

Switching transport vs. setting credentials: The userConfig prompt only configures credentials for stdio mode (Method 1 / Option 1). To switch transport to HTTP, override mcpServers in your client settings per the snippets below — this is a separate path from userConfig and is not driven by the install prompt.

3.1. Hosted (n24q02m.com)

Use the live production endpoint (Dynamic Client Registration + relay form auth):

{
  "mcpServers": {
    "telegram": {
      "url": "https://better-telegram-mcp.n24q02m.com/mcp"
    }
  }
}

The client registers a public DCR client at /register, then opens /authorize to fill the Telegram relay form. The form supports both modes:

• Bot mode — paste your bot token from @BotFather
• User mode — enter your phone number, then the OTP code Telegram sends to your Telegram app, then your 2FA password if enabled

The server bundles public Telegram dev credentials (api_id and api_hash), so users do not need to register at my.telegram.org. After the form completes, the server issues a Bearer JWT and tools become active immediately.

3.2. Self-host with docker-compose

For private deployments (single user or team), clone the repo and run via Docker:

git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
cp .env.example .env
# edit .env: PUBLIC_URL=https://your-domain.com, MCP_DCR_SERVER_SECRET=<32+ random bytes>
docker compose up -d

Bundled Telegram dev credentials (api_id=37984984, api_hash=2f5f4c76c4de7c07302380c788390100) are baked into the image — no my.telegram.org registration needed. Each user authenticates through the relay form (phone + OTP).

Then point your MCP client at your domain:

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

Edge auth: relay password

Public HTTP deployments expose <your-domain>/authorize to URL discovery. To prevent random Internet users from accessing the relay form, mint a relay password:

openssl rand -hex 32
# Save in your skret / .env as:
MCP_RELAY_PASSWORD=<generated-32-byte-hex>

Share this password out-of-band (Signal/email/SMS) with anyone you invite to use your server. They will see a login form when first opening /authorize; once logged in, the cookie persists 24 hours.

Single-user dev exception: If PUBLIC_URL=http://localhost:8080, you can leave MCP_RELAY_PASSWORD empty to disable the gate. The server logs a warning if you skip the password with a non-localhost PUBLIC_URL.

Environment Variables

Stdio Mode (Bot Only)

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	—	Bot token from @BotFather (format: 123456789:ABCdef...)

HTTP Mode (Bot + User)

HTTP mode credentials are entered via the browser-based relay form, not env vars. Server-side env vars for self-hosting:

Variable	Required	Default	Description
PUBLIC_URL	Self-host	—	Public URL of the server (enables multi-user)
MCP_DCR_SERVER_SECRET	Self-host	—	DCR server secret (32+ random bytes)
HOST	Self-host	127.0.0.1	Bind address (0.0.0.0 for Docker)
PORT	Self-host	8000	HTTP port

The bundled Telegram dev api_id (37984984) and api_hash (2f5f4c76c4de7c07302380c788390100) are public dev credentials baked into the source.

Mode Capabilities

Feature	Bot (stdio or HTTP)	User (HTTP only)
Send/Edit/Delete/Forward messages	Y	Y
Pin messages, React	Y	Y
Search messages, Browse history	—	Y
List chats, Create groups/channels	—	Y
Get chat info, Manage members	Y	Y
Send media (photo/file/voice/video)	Y	Y
Download media	—	Y
Contacts (list/search/add/block)	—	Y

Authentication

Stdio Bot Mode

Set TELEGRAM_BOT_TOKEN env var. No web flow — the server connects to the Bot API directly on startup.

HTTP Bot Mode

Open the /authorize URL in any browser, choose Bot Mode, paste your bot token. Done.

HTTP User Mode

Open the /authorize URL in any browser, choose User Mode:

1. Enter your phone number (with country code, e.g., +84912345678)
2. Click submit — Telegram sends an OTP code to your Telegram app (not SMS)
3. Enter the OTP code on the same form
4. If 2FA is enabled, enter your 2FA password (never stored anywhere)
5. The server issues a Bearer JWT, tools become active immediately

Subsequent requests reuse the in-memory session keyed by your JWT subject (sub). Re-authenticate by repeating the /authorize flow.

Verification

After setup, verify the server is working by calling the config tool:

config(action="status")

Expected: returns server status including mode (bot/user), connection state, and session info.

Then test sending a message:

message(action="send", chat_id="me", text="Hello from MCP!")

Note: In bot mode, the bot can only message users who have started a conversation with it.