home / mcp / tgcli mcp server

tgcli MCP Server

Telegram user console client and archiver

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "kfastov-tgcli": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "TGCLI_STORE": "path to app data store"
      }
    }
  }
}

You can enable an MCP server for your Telegram personal account within tgcli to run background synchronization and expose data to an MCP client. This makes it easy to keep your local Telegram data in sync and accessible remotely while maintaining full control over your session.

How to use

To use the MCP server with your client, first enable the MCP feature in your tgcli configuration and then start the server. Your MCP endpoint will be available at the default address http://127.0.0.1:8080/mcp. Point your MCP client to that URL to begin real-time synchronization and remote access to your Telegram data.

Steps you can follow for practical usage:

Enable the MCP server in your configuration: set mcp.enabled to true
Optionally adjust the host and port for the MCP endpoint (defaults are 127.0.0.1 and 8080)
Authenticate with Telegram to allow the CLI to access your MTProto account
Start the MCP service so your client can connect to the endpoint

Example workflow you can reproduce:

- Configure authentication with Telegram API credentials you obtain from my.telegram.org/apps - Enable MCP and optionally customize the bind address and port - Start the server and connect your MCP client to http://127.0.0.1:8080/mcp - Use the client to access messages, channels, and other account data as they are synchronized in real time

How to install

Follow these concrete steps to install tgcli and prepare an MCP server for your personal Telegram account.

# Prerequisites
- Node.js (LTS version) and npm installed on your system
- macOS with Homebrew (optional but recommended)

# Install tgcli (global)
npm install -g @kfastov/tgcli

# Or install from Homebrew (macOS)
brew install kfastov/tap/tgcli

Next, authenticate with Telegram and prepare the MCP server.

tgcli auth

Enable and configure the MCP server, then run it.

tgcli config set mcp.enabled true
# Optional: customize the bind address and port
# tgcli config set mcp.host 127.0.0.1
# tgcli config set mcp.port 8080

tgcli server

Additional sections

Configuration & store: tgcli keeps its configuration and data in the OS app-data directory. The store includes config.json, session files, and messages.db. If you need to place this data elsewhere, set the TGCLI_STORE environment variable to your preferred path before starting tgcli.

MCP endpoint details: The default MCP endpoint binds to http://127.0.0.1:8080/mcp. You can adjust the host and port via the configuration commands shown above. After starting the server, direct your MCP client to the final URL to begin syncing your Telegram data.

Security and usage notes: Only use the MCP server on trusted networks. Keep your Telegram session credentials secure and avoid exposing the MCP endpoint to untrusted clients. If you need to stop the MCP service, use the standard service management commands for your platform.

Available tools

auth

Authenticate with Telegram to set up MTProto session and obtain API credentials.

config

View and edit the tgcli configuration, including enabling MCP and host/port for the MCP server.

sync

Synchronize data by backfilling archives and performing realtime updates.

server

Run the background MCP service that exposes the MTProto data via HTTP.

service

Manage the background service lifecycle (install/start/stop/status/logs).

channels

List and search channels and groups.

messages

List and search messages within chats and channels.

send

Send text or files to users or channels.

media

Download media associated with messages.

topics

Manage and interact with forum topics.

metadata

Cache and access channel metadata for faster lookups.

contacts

Manage contacts and people in your Telegram network.

groups

Manage groups and group memberships.

doctor

Diagnostics and sanity checks to troubleshoot configuration.