Skip to main content
Glama
deenesjakoruzh
z-mio

kurigram-mcp

by z-mio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🤖 kurigram-mcp

使用 AI 调试 Telegram 机器人 —— 一个本地 MCP 服务器，通过 MTProto 驱动你的 Telegram 用户会话。

PyPI Version Python Versions License

English · 简体中文

✨ 特性

🔌 标准 MCP

Streamable HTTP 传输，2026-07-28 协议，向后兼容 2025-11-25 客户端（Claude Code、Codex、DSH）

🧪 机器人调试

发送 /start，测量回复延迟，等待事件，排空更新流

🛠️ 深度调试

对任意 MTProto 函数执行 raw_invoke，内置 API 发现

🔒 聊天白名单

通过请求头按客户端控制，默认 fail-closed

⚡ 无状态

服务器重启不会中断已连接的客户端

🚀 零配置

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