Skip to main content
Glama
deenesjakoruzh
z-mio

kurigram-mcp

by z-mio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🤖 kurigram-mcp

AI로 Telegram 봇 디버깅 — MTProto를 통해 Telegram 사용자 세션을 구동하는 로컬 MCP 서버입니다.

PyPI Version Python Versions License

English · 简体中文

✨ 기능

🔌 표준 MCP

Streamable HTTP 전송, 2026-07-28 프로토콜, 2025-11-25 클라이언트(Claude Code, Codex, DSH)와 하위 호환

🧪 봇 디버깅

/start 전송, 응답 지연 시간 측정, 이벤트 대기, 업데이트 스트림 드레이닝

🛠️ 심층 디버깅

내장 API 탐색 기능과 함께 모든 MTProto 함수에 raw_invoke 실행

🔒 채팅 화이트리스트

요청 헤더를 통한 클라이언트별 제어, 기본적으로 fail-closed

⚡ 무상태(Stateless)

서버 재시작이 연결된 클라이언트에 영향을 주지 않음

🚀 제로 구성

uv tool install, 대화형 설정 마법사, 원커맨드 로그인

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

🚀 빠른 시작

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

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

# 3. Log in (skip if you chose to during setup): phone → code → 2FA
km auth

# 4. Start the server
km run     # default: http://127.0.0.1:8765/mcp

my.telegram.org/apps에서 API_ID / API_HASH를 받으세요. 로그인은 직접 수행해야 합니다 — 자격 증명은 기기를 벗어나지 않습니다.

🧰 도구 (22개)

그룹

도구

🧾 세션

whoami, mcp_get_server_info

📤 전송

send_message, send_photo, send_document, edit_message, delete_message, send_chat_action, start_bot, click_inline_button, send_reaction

📥 읽기

get_chat, get_chat_history, get_messages, get_dialogs, search_messages, download_media

⏱️ 이벤트

wait_for_update, drain_updates

🔬 심층

raw_invoke, list_raw_methods, get_raw_method_info

오류는 안정적인 [CODE] message 형식을 따릅니다: NOT_WHITELISTED · FLOOD_WAIT {seconds} · SESSION_INVALID · RPC · NETWORK · INTERNAL.

🔌 클라이언트 설정

# Claude Code
claude mcp add --transport http kurigram-mcp http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer <AUTH_TOKEN>" \
  --header "X-Kurigram-Allowed-Chats: 6540476263"   # optional per-client whitelist
# Codex (~/.codex/config.toml)
[mcp_servers.kurigram-mcp]
url = "http://127.0.0.1:8765/mcp"
http_headers = { "Authorization" = "Bearer <AUTH_TOKEN>", "X-Kurigram-Allowed-Chats" = "6540476263" }
# 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}`'
      X-Kurigram-Allowed-Chats: '6540476263'

🔐 채팅 화이트리스트

  1. 요청 헤더 X-Kurigram-Allowed-Chats — 클라이언트별 선언(쉼표로 구분: 숫자 채팅 ID, @username, me).

  2. 구성 allowed_chat_ids — 헤더가 없을 때의 대체 수단.

Fail-closed: 화이트리스트에 없는 채팅은 [NOT_WHITELISTED]로 거부됩니다. get_dialogs는 화이트리스트에 등록된 채팅만 반환합니다.

⚙️ 구성

모든 구성은 하나의 파일에 있습니다: ~/.kurigram-mcp/config.yaml.

api_id: 123456
api_hash: your_hash
allowed_chat_ids: "123456789,me"   # fallback whitelist
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

📁 데이터 및 파일

~/.kurigram-mcp/
├── config.yaml         # setup-generated config (chmod 600)
├── u_{API_ID}.session  # Telegram session (bound to API_ID, persists)
└── downloads/          # download_media output

🧑💻 개발

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

📄 라이선스

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

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
    C
    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 npm
    MIT

  • Telegram MCP Server

    tolboy
    A
    license
    Not graded
    quality
    C
    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.
    9
    Apache 2.0