telegram-mcp

Give AI agents access to your Telegram — via MTProto, not Bot API.

What is this?

telegram-mcp is an MCP server that exposes your Telegram account as tools for AI agents. It uses MTProto (userbot protocol) — not Bot API — which means it can access any chat, channel, or DM your account has access to, without needing to add a bot.

Connect it to Claude, Codex, or any MCP-compatible client and let agents read messages, search dialogs, download media, and fetch message links — all from your personal Telegram.

Use Cases

📰 Channel digest Ask your agent to pull the last 50 unread messages from your favorite tech channels, filter for substance, and summarize what's worth reading.

"Fetch unread messages from @some_channel since yesterday and summarize the key points"

🔍 Search your history Find that message with the link someone sent you three weeks ago in a group of 500 people.

"Search my dialogs for 'MCP server' and find where I discussed it"

🤖 Agent inbox monitoring Wire your AI agent to periodically check specific channels and pipe interesting content into your workflow — notes, capture files, summaries.

📎 Media extraction Download files, images, or documents from any message your agent finds — useful for automating research pipelines.

Tools

Full reference with parameters and examples → docs/tools.md

Quick Start

1. Get Telegram API credentials

Go to my.telegram.org, create an app, and grab your API_ID and API_HASH.

2. Install

git clone https://github.com/newink/telegram-mcp.git
cd telegram-mcp
bun install

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

3. Start and authorize via browser

bun start

If no session is configured, the server starts in setup mode and prints an auth URL:

WARN: auth required — open URL to connect Telegram account
      url: "http://localhost:3000/auth?token=a3f9b2c1-..."

Open the URL in your browser — you'll see an auth page where you can sign in with a QR code (scan with Telegram → Settings → Devices → Link Desktop Device) or your phone number. After signing in, the session is saved to .env and the server is ready.

One-time token — the /auth URL is only valid once per server start and expires after successful login. Restarting the server generates a new token.

That's it. Point your MCP client at http://localhost:3000/mcp.

Prefer the terminal? Use bun run auth

bun run auth
# Interactive CLI: QR code or phone number, saves session to .env
bun start

Both flows produce the same result — pick whichever fits your setup.

Docker

Run with Docker Compose — no Bun installation needed:

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

docker compose up

The first time you start the container without a TELEGRAM_SESSION, it will print an auth URL — open it in your browser to sign in. The session is persisted to ./bot-data/ so you only need to auth once.

docker build -t telegram-mcp .

docker run -p 3000:3000 \
  --env-file .env \
  -e ENV_FILE=/app/bot-data/.env \
  -v ./bot-data:/app/bot-data \
  telegram-mcp

Pull pre-built image

# Latest stable
docker pull newink/telegram-mcp

# Or from GitHub Container Registry
docker pull ghcr.io/newink/telegram-mcp

Supported platforms: linux/amd64, linux/arm64 (Raspberry Pi, Apple Silicon via Rosetta).

Connect to Your AI Client

Claude Desktop

Start the server first (bun start), then add to claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

mcporter / OpenClaw

{
  "mcpServers": {
    "telegram": {
      "baseUrl": "http://localhost:3000/mcp"
    }
  }
}

Direct HTTP (any client)

# Initialize session first, then call tools:
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_dialogs","arguments":{"query":"news"}}}'

Environment Variables

*Not required when TELEGRAM_MOCK=true.

Development

bun dev              # Start with hot reload
bun test             # Run tests (uses mock automatically)
bun run typecheck    # TypeScript check
bun run lint         # Biome lint + format
bun run lint:fix     # Auto-fix lint issues
bun run knip         # Find dead code
bun run audit        # Full health check (types + lint + structure + TODOs)

Mock mode — develop and test without a real Telegram account:

TELEGRAM_MOCK=true bun dev   # server with fake data
TELEGRAM_MOCK=true bun test  # run tests

Mock data includes sample dialogs, messages, and media — enough to build and test new tools without touching the real API.

Project structure and architecture → docs/architecture.md MTProto specifics and gotchas → docs/mtproto.md Adding new tools → docs/tools.md

Built With

• Bun — runtime & package manager
• mtcute — MTProto client for TypeScript
• @modelcontextprotocol/sdk — MCP server SDK
• Zod — schema validation
• Biome — linter & formatter

License

MIT