Skip to main content
Glama
deenesjakoruzh
z-mio

kurigram-mcp

by z-mio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

{"type": "text"}

🤖 kurigram-mcp

Depura bots de Telegram con IA — un servidor MCP local que maneja tu sesión de usuario de Telegram a través de MTProto.

PyPI Version Python Versions License

English · 简体中文

✨ Características

🔌 MCP estándar

Transporte HTTP transmisible, protocolo 2026-07-28, compatible con versiones anteriores de clientes 2025-11-25 (Claude Code, Codex, DSH)

🧪 Depuración de bots

Envía /start, mide la latencia de respuesta, espera eventos, drena flujos de actualización

🛠️ Depuración profunda

raw_invoke cualquier función de MTProto, con descubrimiento de API integrado

🔒 Lista blanca de chats

Control por cliente mediante cabecera de solicitud, cerrado por defecto

⚡ Sin estado

Los reinicios del servidor no rompen los clientes conectados

🚀 Cero configuración

uv tool install, asistente de configuración interactivo, inicio de sesión con un comando

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

🚀 Inicio rápido

# 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

Obtén API_ID / API_HASH de my.telegram.org/apps. El inicio de sesión debe realizarlo tú: las credenciales nunca salen de tu máquina.

🧰 Herramientas (22)

Grupo

Herramientas

🧾 Sesión

whoami, mcp_get_server_info

📤 Enviar

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

📥 Leer

get_chat, get_chat_history, get_messages, get_dialogs, search_messages, download_media

⏱️ Eventos

wait_for_update, drain_updates

🔬 Profundo

raw_invoke, list_raw_methods, get_raw_method_info

Los errores siguen un formato estable [CODE] message: NOT_WHITELISTED · FLOOD_WAIT {seconds} · SESSION_INVALID · RPC · NETWORK · INTERNAL.

🔌 Configuración del cliente

# 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'

🔐 Lista blanca de chats

  1. Cabecera de solicitud X-Kurigram-Allowed-Chats — declaración por cliente (separada por comas: IDs de chat numéricos, @username, me).

  2. Config allowed_chat_ids — respaldo cuando la cabecera está ausente.

Cierre por defecto: los chats fuera de la lista blanca se rechazan con [NOT_WHITELISTED]; get_dialogs solo devuelve chats permitidos.

⚙️ Configuración

Toda la configuración vive en un archivo: ~/.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

📁 Datos y archivos

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

🧑💻 Desarrollo

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

📄 Licencia

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