Skip to main content
Glama
deenesjakoruzh
z-mio

kurigram-mcp

by z-mio
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

๐Ÿค– kurigram-mcp

Debug Telegram bots with AI โ€” a local MCP server that drives your Telegram user session over MTProto.

PyPI Version Python Versions License

English ยท ็ฎ€ไฝ“ไธญๆ–‡

โœจ Features

๐Ÿ”Œ Standard MCP

Streamable HTTP transport, 2026-07-28 protocol, backward-compatible with 2025-11-25 clients (Claude Code, Codex, DSH)

๐Ÿงช Bot debugging

Send /start, measure reply latency, wait for events, drain update streams

๐Ÿ› ๏ธ Deep debugging

raw_invoke any MTProto function, with built-in API discovery

๐Ÿ”’ Chat whitelist

Per-account whitelist with global fallback, fail-closed by default

โšก Stateless

Clients stay connected across server restarts

๐Ÿš€ Zero config

uv tool install, interactive setup wizard, one-command login

Related MCP server: io.github.daedalus/mcp-telegram-bot

๐Ÿš€ Quick Start

# 1. Install (provides `kurigram-mcp` and the `km` alias)
uv tool install kurigram-mcp

# 2. One-time setup: API_ID / API_HASH / whitelist / proxy
#    AUTH_TOKEN is auto-generated (Bearer auth on by default)
km setup

# 3. Log in
km session add          # interactive wizard: name โ†’ credentials โ†’ whitelist โ†’ phone โ†’ code โ†’ 2FA

# 4. Start the server (foreground โ€” stop with Ctrl-C)
km run     # default: http://127.0.0.1:8765/mcp

Get API_ID / API_HASH from my.telegram.org/apps. Login must be performed by you โ€” credentials stay on your machine.

๐Ÿ‘ฅ Multi-Account Sessions

Some test scenarios need several users in the same chat (e.g. group bots). Register one account per Telegram user โ€” each account keeps its own session file, optional proxy and chat whitelist โ€” then all accounts live in one server, and every tool takes an account parameter:

# 1. Add each account
km session add alice    # interactive wizard; credentials can reuse the setup app by default
km session add bob

# 2. See login status
km session list          # add -v for proxy/whitelist details

# 3. Edit an account's whitelist / proxy
km session set alice --allowed-chat-ids="-1001234567890,@mybot,me"   # note: use `=` for values starting with `-`
km session set alice --allowed-chat-ids ""   # clear โ†’ fall back to global whitelist
km session set bob --proxy socks5://127.0.0.1:1080   # or --proxy "" to clear

# 4. Start ONE server โ€” all logged-in accounts connect together
km run                   # every tool now accepts account="alice" / account="bob"

  • Every tool (send, read, events, raw, whoami) accepts account: <name> โ€” omit it to use the default account. Example: send_message(account="alice") โ†’ wait_for_update(account="alice").

  • km run --account alice starts a single-account server (isolation mode).

  • The legacy single-account config (api_id at top level) is the implicit account default.

  • Per-account --allowed-chat-ids overrides the global whitelist for that account; accounts without their own whitelist fall back to the global allowed_chat_ids.

  • mcp_get_server_info lists all connected accounts.

๐Ÿงฐ Tools (34)

Group

Tools

๐Ÿงพ Session

whoami, mcp_get_server_info

๐Ÿ“ค Send

send_message, send_photo, send_document, send_voice, send_sticker, send_media_group, send_poll, vote_poll, forward_message, edit_message, delete_message, send_chat_action, start_bot, click_inline_button, send_reaction, send_inline_query

๐Ÿ“ฅ Read

get_chat, get_chat_history, get_messages, get_dialogs, search_messages, get_chat_members_count, download_media

๐Ÿ‘ฅ Group

join_chat, leave_chat

โฑ๏ธ Events

wait_for_update (predicates include is_media / media_type), drain_updates

๐Ÿ”ฌ Deep

raw_invoke, list_raw_methods, get_raw_method_info

๐Ÿ”Œ Client Setup

# Claude Code
claude mcp add --transport http kurigram-mcp http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer <AUTH_TOKEN>"
# Codex (~/.codex/config.toml)
[mcp_servers.kurigram-mcp]
url = "http://127.0.0.1:8765/mcp"
http_headers = { "Authorization" = "Bearer <AUTH_TOKEN>" }
# DSH โ€” cordis.yml plugin row (@deepseek-ai/dsh-mcp-client)
- id: mcp-kurigram
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: kurigram
    transport: streamable-http
    url: http://127.0.0.1:8765/mcp
    headers:
      Authorization: !!js '`Bearer ${process.env.KURIGRAM_TOKEN}`'

๐Ÿ” Chat Whitelist

  1. Per-account whitelist โ€” km session add NAME --allowed-chat-ids "..." (comma-separated: numeric chat ids, @username, me). Each account is isolated.

  2. Global fallback โ€” config allowed_chat_ids applies to any account that didn't set its own.

โš™๏ธ Configuration

All configuration lives in one file: ~/.kurigram-mcp/config.yaml.

api_id: 123456
api_hash: your_hash
allowed_chat_ids: "123456789,me"   # global fallback whitelist (per-account overrides it)
host: 127.0.0.1
port: 8765
auth_token: auto_generated_or_yours # Bearer auth
proxy: ""                           # optional, e.g. socks5://127.0.0.1:1080

๐Ÿ“ Data & Files

~/.kurigram-mcp/
โ”œโ”€โ”€ config.yaml         # setup-generated config (chmod 600)
โ”œโ”€โ”€ sessions/           # Telegram session files: u_{API_ID}.session (one per account)
โ”œโ”€โ”€ downloads/          # download_media output

๐Ÿง‘โ€๐Ÿ’ป Development

uv sync
uv run pytest
uv run ruff check src tests scripts

# Configure like a regular user (shared ~/.kurigram-mcp):
uv run kurigram-mcp setup
# Or isolate a dev environment (never touches your real config):
# KURIGRAM_MCP_HOME=$PWD/.dev-home uv run kurigram-mcp setup
# KURIGRAM_MCP_HOME=$PWD/.dev-home uv run kurigram-mcp run

๐Ÿ“„ License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-telegram

    Prgebish
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that connects AI assistants to your real Telegram account via User API (MTProto). Features default-deny ACL with per-chat permissions, message search, file sending, forwarding, media downloads, and rate limiting.
    3
    MIT

  • io.github.daedalus/mcp

    daedalus
    A
    license
    A
    quality
    C
    maintenance
    MCP server that exposes a Telegram bot, enabling sending messages and retrieving updates through natural language.
    3
    1
    MIT

  • telegram-user-mcp

    22syn
    A
    license
    Not graded
    quality
    B
    maintenance
    An MCP server that connects to Telegram as your real user account and exposes read-only tools to read and search messages, list chats and folders, inspect group info, and download media.
    16
    MIT

  • Telegram MCP Server

    tolboy
    A
    license
    Not graded
    quality
    A
    maintenance
    A safe-by-default MCP server for real Telegram accounts powered by TDLib, enabling AI agents to read and act on your account with read-only mode and human approval for destructive actions.
    5
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/z-mio/kurigram-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server