Telegram Context Gateway Service

Deployment Status (Q3 2025): This service now leverages the official @modelcontextprotocol/sdk transport layer. The backend is powered by the robust MtCute library, utilizing a persistent SQLite database managed by a dedicated asynchronous archiving agent. Migration Notice: MCP consumers are required to connect to the endpoint at http://localhost:8080/mcp. All stored message logs reside within data/messages.db. New utilities govern archival synchronization. For users reliant on the older Server-Sent Events flow, the v0-legacy tag or legacy-0.x branch is maintained. Core Upgrades: Introduction of the standard /mcp interface, integrated MtCute session management, a job queue for message archiving, SQLite persistence layer, and supplementary command-line utilities in client.js.

This specialized MCP gateway empowers intelligent agents (such as Claude or Cursor) to interface with your private Telegram environment, circumventing the limitations of the standard bot API by employing the full user client protocol.

Exposed Capabilities

Function Name	Purpose
`enumerateDialogs`	Retrieves a list of accessible user chats and channels (subject to configured limits).
`locateConversations`	Executes a search across dialog titles or associated usernames.
`fetchDialogContent`	Pulls recent message history from a specified ID or handle, optionally applying RegEx filtering.
`queueArchivalJob`	Initiates a background process to serialize dialog content into the local SQLite store.
`querySynchronizationStatus`	Provides visibility into active archival tasks, their progression cursors, and current states.

Prerequisites for Operation

Runtime Environment: Node.js, version 18 or newer is advised.
Telegram Identity:
- An active Telegram user account is mandatory.
- Security Requirement: Two-Step Verification (2FA) must be actively configured on the account (accessible via Settings → Privacy and Security → Two-Step Verification).
API Credentials:
- Secure an api_id and api_hash by registering a new application via the official portal: https://core.telegram.org/api/obtaining_api_id.

Deployment Procedure

Clone the repository source: bash git clone https://github.com/your-username/telegram-mcp-server.git # Substitute with actual URL cd telegram-mcp-server
Install required software packages: bash npm install

Configuration Setup

Configuration requires setting distinct parameters for the gateway server and the consuming MCP client software.

Gateway Server Configuration:

Set Telegram-specific credentials via environment variables (or within a .env file):

dotenv TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_COUNTRY_CODE_FORMATTED_NUMBER # Example: +15551234567

MCP Client Configuration:

Adjust the configuration manifest of your client application (e.g., Cursor, Claude Desktop) to establish connectivity:

{ "mcpServers": { "telegram": { "url": "http://localhost:8080/mcp", "disabled": false, "timeout": 30 } } }

Ensure you restart the MCP client application for these connection parameters to take effect.

Initiating the Server

Execute the startup script:

bash npm start

The initial launch triggers MTProto authentication. You will be prompted for the Telegram verification code and, if set, your 2FA passphrase. A successful authentication generates a persistent credential file at ./data/session.json, preventing repeat login prompts unless the session token is invalidated.
Direct your MCP client to the established endpoint URL. The client initiates a standard connection sequence (initialize → notifications/initialized → tools/list), automatically handled by the SDK transport. Upon successful handshake, the Telegram toolset should populate the client's interface.

Asynchronous Message Archiving Details

Persistent storage for job metadata and message payloads resides in data/messages.db (SQLite format).
The server processes archival tasks sequentially, incorporating mandated delays between Telegram API calls to proactively manage rate limitations.
Job orchestration is performed via the MCP interface:

queueArchivalJob { "channelIdentifier": -1001234567890 } querySynchronizationStatus {}

The channelIdentifier accepts either the numerical ID or the public handle. Jobs exhibit resilience to server restarts, resuming from their last checkpoint. Job states progress cyclically through pending → in_progress → idle, defaulting to an error state upon persistent failure.

Troubleshooting Common Issues

Repeated Login Prompts: Verify the existence and validity of data/session.json. A manual execution via npm start might be necessary to refresh a stale session. Confirm file system permissions permit R/W access to the data directory by the executing user.
Data Stale/Missing Channels: A simple server reboot forces a refresh of the available conversation roster.
Dependency Failure ("Cannot Find Module"): Ensure npm install has been executed within the primary project directory. If the MCP client launches the server, verify that the current working directory context is correctly established, or resort to absolute path invocation.
Other Anomalies: For unanticipated errors, please file a detailed report in the primary repository issue tracker.

Underlying Telegram Client Library

This project structure includes the core telegram-client.js module utilized by the gateway. Direct exploration of this library for custom scripting purposes can be done by consulting LIBRARY.md.