Skip to main content
Glama
Unofficial Telegram Sales MCP

Unofficial Telegram Sales MCP

by thanhdien938

Unofficial Telegram Sales MCP — 33-Tool Parity

Unofficial, single-user, Windows-first Model Context Protocol (MCP) server providing full 33-tool functional parity with Telegram Sales Plugin v1. Not affiliated with or endorsed by Telegram. First-party source code is licensed under MIT.

This release restores complete capability across Telegram reads, authorized Telegram actions, and local Sales CRM persistence:

  • 11 Telegram Read tools (health, capabilities, account profile, chat lists, chat inspection, unread inbox, message history, messages search, public search, contacts directory, bounded file retrieval).

  • 13 Telegram Action tools (send, reply, edit, delete, forward, reaction add, reaction remove, pin, unpin, mark-read, media send, text schedule, media schedule).

  • 9 Sales CRM tools (lead upsert, lead get, lead list, group tracking, group list, quick-reply template upsert, quick-reply list, quick-reply preview, and quick-reply send).

Architecture and Safety Controls

  • Single-User Target Binding: Outbound Telegram actions are disabled by default. When explicitly enabled via --writes --chat-id <CHAT_ID> (or environment variables TELEGRAM_SINGLE_USER_WRITES=1 and TELEGRAM_SINGLE_USER_CHAT_ID=<CHAT_ID>), every mutation is strictly constrained to the single operator-approved chat. The model cannot supply arbitrary recipient IDs.

  • Idempotency & Audit Ledger: All write operations enforce unique client request keys and store cryptographic SHA-256 fingerprints to guarantee strict deduplication and audit traceability.

  • Local SQLite CRM: Sales leads and quick-reply templates are stored in a local SQLite database requiring explicit operator consent before database creation.

  • Isolated Native TDLib Wrapper: A Python 3.11+ ctypes wrapper interfaces with the official TDLib JSON C API (tdjson.dll), enforcing frame boundaries, log stream suppression, and dedicated subprocess isolation.

  • Windows DPAPI Vault: Sensitive session metadata and account credentials are encrypted at rest using Windows CurrentUser Data Protection API (DPAPI).

  • Diagnostics First: Built-in doctor command inspects local Node, Python, native DLL manifests, session roots, and CRM stores, outputting clear health status and remediation steps.

Related MCP server: Telegram MCP Server

Tool Inventory (33/33 Parity)

Category

Count

Tools

Telegram Read

11

telegram_health, telegram_capabilities, telegram_account, telegram_chats_list, telegram_chat_get, telegram_inbox, telegram_messages_get, telegram_messages_search, telegram_public_search, telegram_contacts, telegram_file_get

Telegram Action

13

telegram_message_send, telegram_message_reply, telegram_message_edit, telegram_message_delete, telegram_message_forward, telegram_message_reaction_add, telegram_message_reaction_remove, telegram_message_pin, telegram_message_unpin, telegram_message_mark_read, telegram_message_media_send, telegram_message_text_schedule, telegram_message_media_schedule

Sales CRM

9

telegram_sales_lead_upsert, telegram_sales_lead_get, telegram_sales_leads_list, telegram_sales_group_track, telegram_sales_groups_list, telegram_sales_quick_reply_upsert, telegram_sales_quick_replies_list, telegram_sales_quick_reply_preview, telegram_sales_quick_reply_send

Quick Start on Windows

1. Prerequisites

  • Operating System: Windows 10/11 64-bit (x64)

  • Node.js: v22.19.0 or higher

  • Python: v3.11+ 64-bit (standard distribution with ctypes)

  • TDLib: 64-bit tdjson.dll (built from official upstream source or acquired from vetted release)

2. Install & Build

npm ci --ignore-scripts --userconfig .npmrc --globalconfig config/npm-globalrc
npm run build
npm run test:offline

3. Run Doctor Check

npm run doctor

The doctor diagnostics will report the status of Node, Python, TDLib manifest/DLL, session root, CRM database, and write opt-in configuration.

4. Setup Steps

Refer to INSTALL.md and RUNBOOK.md for full setup instructions:

  1. Generate native TDLib manifest in an external directory:

    node scripts/generate-native-manifest.mjs --dll "<PATH_TO_TDJSON_DLL>" --commit "<TDLIB_COMMIT_SHA>" --out "<USER_NATIVE_BUNDLE_DIR>"
  2. Authenticate account in private terminal: node dist/login.js --state <STATE_DIR> --native-manifest <MANIFEST_PATH> --python <PYTHON_EXE>

  3. Initialize local CRM database: node dist/crm-init.js <CRM_DIR>

  4. Launch MCP Server with 33 tools:

    node dist/cli.js --crm <CRM_DIR> --state <STATE_DIR> --native-manifest <MANIFEST_PATH> --python <PYTHON_EXE> --writes --chat-id <TARGET_CHAT_ID>

License and Notices

First-party TypeScript and Python code is licensed under MIT. Upstream TDLib is licensed under the Boost Software License 1.0. See THIRD_PARTY_NOTICES.md and SECURITY.md.

Available Tools

11 tools
telegram_accountB

Reports the safe, redacted snapshot, reauth state, and runtime health of the Telegram user account without exposing secrets or identity values.

Inputs: no named parameters.

telegram_capabilitiesB

Reports the explicit capability manifest and status for the Telegram sales plugin foundation and account runtime.

Inputs: no named parameters.

telegram_chat_getB

Retrieves normalized details and permissions for a specific chat by chat_id. Read only.

Inputs: chat_id (required).

telegram_chats_listC

Lists recent chats with bounded pagination and normalized summaries. Read only.

Inputs: limit, cursor, chat_list.

telegram_contactsA

Lists or searches known Telegram user contacts with safe privacy projection. Phone number values are never exposed (phone_number_present fact only). Read only.

Inputs: mode (required), limit, query.

telegram_file_getA

Retrieves metadata or bounded base64 content for a Telegram file by file_id. Accepts ONLY Telegram file_id (int32 decimal string). Arbitrary file paths or URLs are strictly forbidden. Content reads are bounded to at most 262144 bytes (256 KB). Read only.

Inputs: mode (required), file_id (required), max_bytes.

telegram_healthB

Reports the health and provider status of the Telegram sales plugin foundation and account runtime.

Inputs: no named parameters.

telegram_inboxB

Returns a read-only projection of recent and unread conversations without marking anything read. Output contains page/scan-scoped returned_count, unread_in_scan, and raw_scanned_count.

Inputs: limit, cursor, unread_only.

telegram_messages_getB

Fetches recent message history or context around a specific message in a chat in deterministic order. Read only.

Inputs: chat_id (required), mode, after, limit, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions, such as messages_get vs. messages_search vs. public_search vs. file_get. There is some overlap between telegram_chats_list and telegram_inbox, and between telegram_health, telegram_capabilities, and telegram_account, but the descriptions give enough separation to avoid serious misselection.

    Naming Consistency3/5

    All tools share the telegram_ prefix, but the suffix conventions are mixed: some are noun-only (telegram_health, telegram_account, telegram_inbox), while others use resource_action (telegram_chats_list, telegram_chat_get, telegram_messages_search). There is also singular/plural inconsistency between telegram_chats_list and telegram_chat_get. The names remain readable, but the pattern is not fully predictable.

    Tool Count5/5

    Eleven tools is a reasonable size for a Telegram-focused server and stays within the well-scoped 3-15 range. Each tool appears to earn its place by covering a specific read/search/health capability.

    Completeness2/5

    The surface is entirely read-only and lacks core Telegram sales operations such as sending messages, managing chats or contacts, uploading files, or performing account reauthentication actions. While the read/search/health coverage is fairly broad, the absence of write or lifecycle operations is a significant gap for a sales-oriented Telegram MCP.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Privacy-first Telegram MCP server enabling maintainers to triage chats, inspect context, search messages, draft replies, and send authorized messages locally without a cloud relay.
      57 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server that acts as a gateway to Telegram, providing AI-optimized tools for messaging, search, and chat management via MTProto. Supports multi-user authentication with QR login and HTTP/stdio transports.
      8
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables local, privacy-first control of a personal Telegram account through MCP, using TDLib to read chats, send and reply to messages, search, transfer files, and interact with approved inline buttons.
      20
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to read and search Telegram chats, fetch media, export messages, inspect channel analytics, build a local index, and prepare confirmed replies, sends, reactions, joins, and callback button presses across multiple accounts through one daemon.
      MIT