Unofficial Telegram Sales MCP
Based on the provided schema, this server exposes 11 read-only Telegram tools for inspection and lookup (the README advertises additional action/CRM tools not present in the schema).
Check runtime health, declared capabilities, and redacted account status.
List recent chats, inspect a chat by ID, and view unread/recent inbox conversations without marking read.
Fetch message history/context and search messages within a chat or account.
Search public Telegram usernames/chats/posts/tags.
List/search contacts with phone numbers hidden.
Retrieve Telegram file metadata or up to 256 KB of content by
file_idonly.No message sending, editing, deleting, reactions, pins, scheduling, or Sales CRM operations are exposed by this schema.
Unofficial single-user Telegram integration exposing read-facing tools for exploring chats, messages, contacts and file metadata (search, contacts, file metadata sources) via TDLib, with all write actions (send, reply, edit, delete, forward, reactions, pins, media, scheduling) hard-disabled. Native TDLib runtime build and real authenticated Telegram login/reads are currently gated/unqualified, so the Telegram provider reports NOT_CONFIGURED until a developer independently builds and validates the native runtime and session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unofficial Telegram Sales MCP show my tracked Telegram sales groups and recent CRM leads"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 variablesTELEGRAM_SINGLE_USER_WRITES=1andTELEGRAM_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
doctorcommand 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 Action | 13 |
|
Sales CRM | 9 |
|
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:offline3. Run Doctor Check
npm run doctorThe 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:
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>"Authenticate account in private terminal:
node dist/login.js --state <STATE_DIR> --native-manifest <MANIFEST_PATH> --python <PYTHON_EXE>Initialize local CRM database:
node dist/crm-init.js <CRM_DIR>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 toolstelegram_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.
telegram_messages_searchB
Searches for messages within a specific chat or across the entire account in reverse-chronological order. Read only.
Inputs: scope (required), limit, query, cursor, +6 more.
telegram_public_searchB
Searches for public Telegram entities: exact username, public chats by title/username query, public channel posts, or public messages by hashtag/cashtag. Public posts search is strictly free (star_count=0); stars payment is disabled. Read only.
Inputs: mode (required), tag, limit, query, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
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.
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.
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.
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
Unofficial remote MCP server for Less Annoying CRM: OAuth 2.1, read-only grants, 10 tools.
Unified inbox MCP for WhatsApp, Telegram, Email, voice — read/send messages, search, AI agents.
Unified messaging MCP server: WhatsApp, Instagram, Telegram, SMS, Messenger & email support inbox
Second Shift agent-native MCP server: a machine-readable front door to client leads.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePrivacy-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 npm1MIT
- AlicenseAqualityCmaintenanceMCP 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.82MIT
- AlicenseAqualityCmaintenanceEnables 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.20MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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