🤖 kurigram-mcp

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

English · 简体中文

✨ Features

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.

• Short flags: km run -a/--account -H/--host -p/--port -u/--public-url -s/--stateful; km session add/set -x/--proxy -c/--allowed-chat-ids; km -V/--version.

🧰 Tools (36)

🔌 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.

📁 Remote File Transfer

Remote MCP clients can't reach the server's local filesystem, so media transfer goes through short-lived signed URLs (presigned-URL pattern):

• Download — get_media_url(chat_id, message_id) returns {url, file_name, mime_type, size_bytes}; curl -o <file_name> '<url>' fetches the media over plain HTTP (GET /files/<chat>/<msg>, Range supported for resume).

• Upload — create_upload_url(file_name) returns {url, media}; curl -T <local file> '<url>' PUTs the file into a per-upload staging dir, then pass media (upload://<uid>/<name>) directly to send_photo / send_document / send_voice / send_sticker / send_media_group / send_rich_message.

Tokens are HS256 JWTs signed by an in-process key (a restart invalidates all outstanding URLs), each bound to a single resource, expiring after file_url_ttl_seconds (default 900s). Upload URLs are single-use; staged files are cleaned up after upload_retention_hours (default 24h).

For humans and scripts, the master AUTH_TOKEN is also accepted — via the Authorization: Bearer header only (never as ?token=):

curl -T a.png -H "Authorization: Bearer $AUTH_TOKEN" http://host:port/upload/a.png
curl -H "Authorization: Bearer $AUTH_TOKEN" -o x http://host:port/files/<chat_id>/<message_id>

Public URL (reverse proxy / Cloudflare Tunnel): when the server is reached from outside, pass -u, --public-url so generated upload/download links point at the external address — the proxy rewrites the Host header, which is why the server never derives URLs from requests. Not needed for local-only use:

km run --public-url https://kurigram.example.com

(PUBLIC_BASE_URL env or public_base_url in config.yaml work too; the flag wins.) Note that Cloudflare's proxy caps request bodies at 100 MB on Free/Pro plans: larger uploads through the tunnel get a 413 from Cloudflare itself (downloads are unaffected).

⚙️ 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
public_base_url: ""                 # public URL when reached from outside (e.g. tunnel domain); skip for local-only use
file_url_ttl_seconds: 900           # signed file URL lifetime
upload_max_bytes: 2147483648        # per-upload size cap (2 GiB)
upload_retention_hours: 24          # staged upload retention before cleanup
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
├── uploads/            # create_upload_url staging (per-uid dirs, auto-cleaned after retention)

🧑‍💻 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