Telegram MCP Server

Telegram MCP for real accounts — safe by default, TDLib-powered, production-ready.

A local-first Model Context Protocol server that gives an AI agent real Telegram-account access without handing it the keys to your account. It starts read-only, hides write tools until you opt in, and runs over STDIO for desktop clients or Streamable HTTP at /mcp for managed deployments.

Why this one?

• Safe by default — boots in read-only mode with a small inbox/reader profile; write and quota-consuming tools are hidden from the model, not merely blocked, until you turn them on.

• Human approval that does not depend on your client — destructive tools ask a person first: through the MCP host where elicitation exists, otherwise on a single-use loopback page this server hosts. Either way the question leaves and the answer returns outside the model's turn, so an injected instruction can make the model request a ban, not approve one.

• Real user accounts, not just bots — built on TDLib (via tdlight-java), so an agent can read and act on your actual account, not only a Bot API subset.

• Isolated multi-account — each account gets its own session, mandatory selection, and scoped API keys; reads never fan out across accounts.

• Two transports — STDIO for Claude Desktop / Cursor / VS Code / Codex, Streamable HTTP for a managed service.

• No JDK to install — runtime-inclusive release bundles for Windows, Linux x64/ARM64, and Apple-silicon macOS, with checksums, an SBOM, and signed container digests.

The image is an illustrative mockup; a real screencast is on the way.

Safe first run

Runtime-inclusive releases need no JDK, Gradle, Git, Python, or Node.js. Use a test account for your first run if you can.

1. Install (macOS Apple silicon / Linux with Homebrew):

brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb

Windows with Scoop:

scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json

2. Log in with a QR scan — the one-time code never touches your shell history:

telegram-mcp auth --method qr

3. Check the session is ready — this reads local state and starts no server:

telegram-mcp session doctor

Do not run serve --transport stdio yourself to try it out. With STDIO your AI client starts the server and owns its lifetime; a copy you launched in a terminal holds the TDLib session, and the client's own copy then exits with code 2 because it cannot lock td.binlog. Give the command to the client instead (below) and let it do the starting.

Then try a first prompt that cannot change anything:

“Summarize my last 20 conversations. Do not send or modify anything.”

In this mode write and quota-consuming tools are absent from the tool list entirely, so the model has nothing destructive to call. Switch to MCP_READ_ONLY=false only after you have reviewed the surface. When you do, add MCP_DESTRUCTIVE_APPROVAL=auto so deletes, bans and leaves wait for your answer through host elicitation where available, or through the server's loopback page otherwise, rather than trusting the model's own "confirmed": true.

Related MCP server: MCP Telegram

Connect your client

Generate the entry instead of transcribing one — it fills in the key your client actually expects and pins the version it was generated from:

telegram-mcp config --client claude

--client claude-code|cursor|vscode|codex switches target — Codex gets TOML, VS Code gets the servers key it actually reads, Claude Code gets the explicit transport type. --writes enables write tools and the approval prompt that guards the destructive ones — pair it with a write-capable --profile inbox|community-admin|all, since the default reader surface hides write tools before read-only mode is consulted. --docker default emits a container entry with a pinned image, and --http default emits the shared-daemon entry for Claude Code, Cursor, VS Code, or Codex. Claude Desktop does not read remote servers from claude_desktop_config.json; add a network-reachable remote endpoint under Settings → Connectors instead. Claude remote connectors do not accept the generator's custom API-key header, so this server must be exposed over HTTPS with MCP_AUTH_MODE=oauth. The generator therefore rejects --client claude --http.

STDIO is the low-friction path for desktop clients. The generated entry looks like:

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "TDLIB_API_ID": "123456",
        "TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
        "MCP_TOOL_PROFILE": "inbox",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

• Claude Desktop — add the block above to claude_desktop_config.json, then quit the app from the tray and start it again. Use Settings → Developer → Edit Config to open the file: it points at the right copy for your build. Editing %APPDATA%\Claude by hand works only for the installer build — the Microsoft Store build is packaged as MSIX and keeps its config in %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ instead.

• Cursor — add it to ~/.cursor/mcp.json (or Settings → MCP → Add).

• VS Code — use .vscode/mcp.json; VS Code names the top-level key servers instead of mcpServers and requires an explicit "type": "stdio" or "type": "http".

For a managed HTTP deployment instead of STDIO:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e TDLIB_API_ID -e TDLIB_API_HASH -e MCP_API_KEY \
  ghcr.io/tolboy/telegram-mcp-tdlib:latest

See CLI and STDIO, interactive authentication, and client compatibility for exact platform/client variants.

Recipes

Copy-paste configurations and prompts for real tasks, each with the smallest tool surface that can do the job: summarize your inbox, find a lost message, research public groups, read-only community health check, and draft replies without sending — index in docs/recipes.

How it compares

Most Telegram MCP servers wrap the Bot API or a Telethon user session and expose every capability to the model at once. This project optimizes for connecting an agent to a real account you care about, safely:

A fuller architectural comparison (TDLib vs Telethon vs Bot API, and why "hidden, not blocked" matters) is in docs/COMPARISON.md. The detailed, dated benchmark against the leading public servers — including features deliberately declined (raw MTProto escape hatch, ownership transfer, bulk contact export) — is in PUBLIC_BENCHMARK_AND_ROADMAP.md.

Tool profiles

You don't expose 110 tools on day one. MCP_TOOL_PROFILE narrows the advertised surface before a client ever sees it, without weakening account scoping, read-only mode, confirmation, audit, or anti-spam:

See TOOL_PROFILES.md for the exact intent of each surface.

Features

• 110 MCP tools — messages, polls, read receipts, scheduled sends, chats, folders, invite-link administration, contacts, media, drafts, privacy, bot commands, detailed group permissions, profile, search, and account routing.

• TDLib via tdlight-java — real user accounts, not just the Bot API.

• Isolated multi-account mode — independent sessions, mandatory account selection, and optional per-key account scopes with no cross-account read fan-out.

• Safe by default — read-only tool surface, human approval for destructive actions (MCP_DESTRUCTIVE_APPROVAL, over the host or a loopback page), and task-focused profiles (reader/inbox/community-admin/research/all).

• Two transports — STDIO for desktop clients and Streamable HTTP /mcp (Spring AI 2.0 / MCP SDK 2.0), with API-key auth.

• Guardrails — audit logging, anti-spam via Resilience4j rate limiter (30 req/s) and circuit breaker, chat allow-list, prompt-injection patterns, and untrusted-content marking.

• Observability — Micrometer metrics, Prometheus endpoint, and structured JSON logging with MDC (traceId, sessionId, toolName).

• Verified, runtime-inclusive releases — Windows x64, Linux x64/ARM64, and Apple-silicon macOS bundles with checksums, an SBOM, and signed container digests — no JDK required.

• Entity resolution — resolve @username, +phone, or numeric IDs transparently.

• MCP behavior annotations — every advertised tool declares read-only, destructive, retry, and open-world hints for safer client UX.

• Structured, marked output — backward-compatible JSON text plus structuredContent; Telegram-controlled fields are explicitly untrusted and presentation-control Unicode is escaped.

• Host-friendly discovery via /.well-known/mcp-server.json for installers, desktop hosts, and service managers.

• File security service for safe media uploads; Actuator health/info/metrics; graceful shutdown with configurable timeout.

• Multi-stage Docker build + docker-compose with dev hot-reload.

• Runtime-inclusive app images — the supported release archives include their own Java runtime and pass an actual STDIO handshake before publication.

• Offline session doctor — inspect configured TDLib state paths and lock availability without starting TDLib or printing secrets.

• Clean Architecture — config / model / client / service / tool / security / util / exception.

• Language-neutral public search — callers pass synonyms, translations, and spelling variants in any language; product-specific policy interpretation stays in the MCP host.

Tech Stack

Quick Start

Prerequisites

• Java 25+ (or use Docker)

• Telegram API credentials from https://my.telegram.org (TDLIB_API_ID, TDLIB_API_HASH)

• Exactly one authentication mode: TDLIB_PHONE_NUMBER for user-account mode or TDLIB_BOT_TOKEN for bot mode

1. Clone and configure

git clone https://github.com/tolboy/telegram-mcp-tdlib.git
cd telegram-mcp-tdlib
cp .env.example .env
# Edit .env — set TDLIB_API_ID, TDLIB_API_HASH, one of TDLIB_PHONE_NUMBER/TDLIB_BOT_TOKEN, and MCP_API_KEY

On Windows PowerShell, use Copy-Item .env.example .env instead of cp.

2. Run locally

./gradlew bootRun

The server starts on http://localhost:8080. Its MCP Streamable HTTP endpoint is http://localhost:8080/mcp.

Your first 60 seconds

1. Add a remote Streamable HTTP MCP server in your client with URL http://127.0.0.1:8080/mcp and Authorization: Bearer <MCP_API_KEY>. Cursor, VS Code, Codex, Claude Code, and Inspector can use that local HTTP endpoint. Claude Desktop's config file supports the local STDIO entry above; its remote connectors are added through Settings → Connectors and require a network-reachable HTTPS endpoint with MCP_AUTH_MODE=oauth, rather than this loopback URL plus a custom header. Exact connection data is kept in MCP_CLIENT_COMPATIBILITY.md.

2. Start safely with MCP_READ_ONLY=true and one focused surface, for example MCP_TOOL_PROFILE=inbox or MCP_TOOL_PROFILE=research.

3. Ask the client one of these concrete first questions:

   • Inbox: “Summarize my last 20 relevant conversations. Do not send or modify anything.”

   • Community: “Show recent admin actions and default permissions in this group; propose changes, but do not apply them.”

   • Research: “Find public chats matching these English and Russian query variants, and report evidence from descriptions and recent messages.”

Switch to MCP_READ_ONLY=false only after reviewing the discovered surface; confirmation remains enabled by default for destructive actions.

On Windows, Gradle outputs default to the system temp directory to avoid file-lock issues in synchronized folders. Set KTM_BUILD_DIR or pass -Pktm.buildDir=... to override.

3. Run with Docker

docker compose up --build

The compose stack persists TDLib session data in the tdlib-data volume, downloads in telegram-downloads, and mounts ${MCP_UPLOADS_DIR:-./docker-data/uploads} into the container as /data/uploads for upload/download tools.

By default, compose binds the service to 127.0.0.1 via MCP_BIND_HOST so the local boxed/developer scenario is not exposed on the LAN by accident.

Dev mode with hot-reload:

docker compose --profile dev up telegram-mcp-dev

With Prometheus monitoring:

docker compose --profile monitoring up

Production note: terminate TLS in front of the container (reverse proxy, ingress, or load balancer). API keys should not traverse plaintext HTTP outside trusted local development networks.

Deployment guidance for local boxed installs vs remote/VPS exposure is documented in docs/DEPLOYMENT_MODES.md.

Connector discovery for a multi-server MCP host or installer is documented in docs/CONNECTOR_DISCOVERY.md.

Client compatibility, a portable JSON-Schema profile, and a Streamable HTTP smoke test are documented in MCP_CLIENT_COMPATIBILITY.md.

Offline-safe TDLib session inspection and clearing are documented in SESSION_MAINTENANCE.md.

The comparison with the leading public Telegram MCP servers and the prioritized follow-up work are documented in PUBLIC_BENCHMARK_AND_ROADMAP.md.

Releases

CI runs on every pull request and push to master. A signed-off release is a Git tag in the vX.Y.Z form; the release workflow builds the images, runs the cross-platform tool-surface smoke and the container lifecycle contract against the pushed digest, attests and signs it, and only then moves the public tags (latest, X.Y.Z, X.Y, immutable sha-<commit>, and the -stdio variants) onto that exact digest — verifying afterwards that each tag resolves to it. Release bundles for Windows x64, Linux x64/ARM64, and macOS ARM64 ship alongside. Public releases include an SPDX SBOM for the runnable JAR, GitHub provenance attestations for release assets, and a keyless Sigstore signature plus provenance for the container digest. See release-bundle verification.

Use a concrete semver tag for reproducible deployments. v1.0.0 is the first Streamable HTTP / MCP SDK 2.0 public baseline; v1.1.0 adds account isolation, scoped keys, and cross-platform native packaging; v1.2.0 adds premium voice-note transcription and the neutral package namespace; v1.3.0 adds privacy, bot-command, detailed group-permission controls, and verified release bundles; v1.4.0 adds focused MCP tool profiles; v1.7.x adds the STDIO transport, CLI with an interactive auth wizard, structured tool output, optional OAuth resource-server mode, and runtime-inclusive release images; v1.13.0 adds human approval for destructive tools over the host or a loopback page, and telegram-mcp config to generate client entries; v1.14.0 ties every published image tag to the digest that passed verification and signing. The complete history is in CHANGELOG.md.

The current TDLight native release publishes an Apple-silicon macOS binary but not an Intel macOS classifier. The server supports Intel macOS at the JVM/path level, but TDLib-backed Telegram access on that platform requires an upstream native package before it can run.

To create the runtime-inclusive app image for the current matching platform:

./scripts/package-app-image.ps1 -Version <version> -Target windows-x64 -OutputDirectory release-assets

The build verifies the actual BOOT-INF/lib contents, launcher-reported version, and a live STDIO handshake. See RELEASE_BUNDLES.md for the target matrix.

git checkout master
git pull --rebase origin master
git tag -a vX.Y.Z -m "Telegram MCP Server vX.Y.Z"
git push origin master vX.Y.Z

Environment Variables

TDLib (primary Telegram client)

* Required when TDLib integration is enabled.
† Set exactly one: TDLIB_PHONE_NUMBER or TDLIB_BOT_TOKEN.

Non-interactive auth: on a fresh container, set TDLIB_AUTH_CODE once (plus TDLIB_2FA_PASSWORD if 2FA is enabled). After the session persists to TDLIB_DATA_DIR, neither is needed on restart. Every direct secret setting has a mutually exclusive *_FILE alternative for Docker/Podman/Kubernetes secret mounts.

For a local first-time login without putting the one-time code in the environment, use the phone/code or QR flow documented in INTERACTIVE_AUTH.md. TDLIB_DEVICE_MODEL and TDLIB_SYSTEM_LANGUAGE_CODE control the recognizable session identity shown under Telegram Settings → Devices.

At-rest encryption note: SimpleTelegramClient (tdlight-java) does not expose the TDLib database-encryption key. For production, encrypt the TDLIB_DATA_DIR volume at the filesystem level (LUKS, FileVault, EFS) rather than relying on a library-level flag. Additional use-file-database, use-chat-info-database, use-message-database toggles are available in TdLibProperties.kt.

Telegram proxy

The server configures TDLib's own proxy before login, so it covers both initial authentication and normal Telegram traffic. Use one of these complete configurations; incomplete or invalid proxy settings make startup fail before the account can connect.

# SOCKS5 with optional username/password authentication
TDLIB_PROXY_TYPE=socks5
TDLIB_PROXY_SERVER=proxy.example.net
TDLIB_PROXY_PORT=1080
TDLIB_PROXY_USERNAME=connector
TDLIB_PROXY_PASSWORD_FILE=/run/secrets/telegram_proxy_password

# HTTP CONNECT (set HTTP_ONLY=false to route all TDLib traffic through it)
# TDLIB_PROXY_TYPE=http
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=3128
# TDLIB_PROXY_HTTP_ONLY=false

# MTProto (secret must be supplied directly or through *_FILE)
# TDLIB_PROXY_TYPE=mtproto
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=443
# TDLIB_PROXY_SECRET_FILE=/run/secrets/telegram_mtproto_secret

Named accounts can have independent settings using TELEGRAM_ACCOUNTS_<LABEL>_PROXY_*, for example TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=socks5. An account proxy never falls back to another account's credentials or TDLib session. When using *_FILE inside Docker, mount the secret file into the container and set the container path.

Server & Security

* When blank in API-key mode, protected endpoints accept only direct loopback requests. Non-loopback requests to /mcp, /actuator/metrics, and /actuator/prometheus are rejected. Container images bind inside their network namespace and therefore require either a configured API key or OAuth bearer protection for MCP access through a published port or Docker bridge.

Compose-only convenience variables:

• MCP_UPLOADS_DIR controls the host directory mounted into the container as /data/uploads.

• KTM_BUILD_DIR overrides Gradle's build directory for local builds without changing the project default.

Tool profiles

MCP_TOOL_PROFILE reduces the advertised surface before a client sees it; it does not weaken account scoping, allow-lists, read-only mode, confirmation, audit, or anti-spam controls. reader is always non-mutating. inbox keeps personal messages, drafts, media, contacts, and privacy settings; community-admin keeps moderation, group/channel, permission, and bot-command workflows; research keeps bounded account/public discovery and reading.

The active profile appears in /.well-known/mcp-server.json and _manifest. See TOOL_PROFILES.md for the exact intent of each surface.

Multi-account setup

Use suffixed environment variables per label. Labels are normalized to lowercase and must contain only a-z, 0-9, _, or -; they never expose a profile name, phone number, or token.

TELEGRAM_ACCOUNTS_WORK_API_ID=12345
TELEGRAM_ACCOUNTS_WORK_API_HASH_FILE=/run/secrets/work_api_hash
TELEGRAM_ACCOUNTS_WORK_PHONE_NUMBER=+15551234567

TELEGRAM_ACCOUNTS_PERSONAL_API_ID=12345
TELEGRAM_ACCOUNTS_PERSONAL_API_HASH_FILE=/run/secrets/personal_api_hash
TELEGRAM_ACCOUNTS_PERSONAL_PHONE_NUMBER=+15557654321

TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=mtproto
TELEGRAM_ACCOUNTS_WORK_PROXY_SERVER=proxy.example.net
TELEGRAM_ACCOUNTS_WORK_PROXY_PORT=443
TELEGRAM_ACCOUNTS_WORK_PROXY_SECRET_FILE=/run/secrets/work_mtproto_secret

Each account receives a separate TDLib database and downloads directory below the platform app-data directory unless explicitly overridden. In multi-account mode every Telegram tool requires an account argument. This server intentionally does not fan read requests out to all accounts: omission must fail closed rather than disclose data from the wrong account. Call list_accounts to discover labels visible to the authenticated MCP client.

For remote MCP clients, prefer one scoped key per client:

MCP_SECURITY_CLIENTS_0_ID=work-agent
MCP_SECURITY_CLIENTS_0_API_KEY_FILE=/run/secrets/work_mcp_key
MCP_SECURITY_CLIENTS_0_ALLOWED_ACCOUNTS_0=work

An empty allowed-accounts list permits all configured accounts; use it only for an administrator key. The legacy MCP_API_KEY remains supported for single-account and trusted-local deployments.

API Key Authentication

The server always supports these standard header formats:

Authorization: Bearer <your-api-key>

or

X-MCP-API-Key: <your-api-key>

If MCP_AUTH_HEADER is set to another header name, that header is accepted as well.

When configured through mcp.security.clients, each authenticated key carries an optional account allow-list that is enforced before a tool reaches TDLib.

Public endpoints (no auth needed):

• GET /actuator/health

• GET /actuator/info

• GET /.well-known/mcp-server.json

The well-known descriptor is intentionally small and stable. It helps generic installers or orchestration layers discover a single-purpose connector without turning this server into an in-process aggregator.

Interactive /auth/** endpoints are keyless only from loopback. Requests from a Docker bridge, reverse proxy, or private LAN must include the configured MCP API key; private IP space is not treated as a trusted identity.

The same fail-closed rule applies to /mcp and protected Actuator endpoints when API-key mode has no configured key. Raw HTTP binds to 127.0.0.1 by default; a remote deployment must deliberately change SERVER_ADDRESS and configure an API key or OAuth.

Orchestration And Tool Binding

This repository is an MCP connector (tool server), not an autonomous agent runtime.

TDLib access alone does not make an LLM call Telegram tools. For end-to-end behavior, an external MCP host, agent loop, or orchestration service must:

1. Discover tool schemas from this MCP server.

2. Send those tool schemas to the model for the current turn.

3. Execute model-requested tool calls against this MCP server.

4. Feed tool results back into the model until a final assistant answer is produced.

Without that orchestration layer, prompts are handled as plain text generation and no Telegram actions are executed.

If you use a multi-connector router, prefer explicit connector scoping per chat request so Telegram turns expose Telegram tools only.

Safety Model

Telegram account credentials and TDLib session data are sensitive. Start with a test account where practical, bind the service to localhost, use a long random MCP_API_KEY, and keep MCP_READ_ONLY=true until you intentionally need writes. In read-only mode write and quota-consuming tools are absent from the MCP tool list; the execution guard remains as defense in depth. MCP_CONFIRMATION_REQUIRED=true adds a caller-acknowledgement step for destructive actions, but the server cannot prove that "confirmed": true came from a human: that flag travels inside the tool call, so a model acting on a malicious message can set it itself.

MCP_DESTRUCTIVE_APPROVAL=auto closes that gap. Before each destructive tool a person is asked, and the answer comes back over a channel the model does not write to — so an injected instruction can make the model request a ban, but not approve one. The check runs before any Telegram call.

Where the question appears depends on the client. Hosts that implement MCP elicitation show their own prompt. Most do not — Claude Desktop advertises no elicitation capability — so auto falls back to a page this server hosts on 127.0.0.1, announcing the link on stderr where your client shows server output. That is not a weaker answer: the link is single use, nonce-protected, reachable only from your machine, and expires into a refusal. Force one route with elicitation or loopback if you would rather fail than fall back. This is the setting to enable on an account you care about.

The loopback page belongs to the server process. Inside an un-published Docker network namespace, its 127.0.0.1 is the container's, not yours, so no host browser can open it. telegram-mcp config --docker ... --writes therefore generates MCP_DESTRUCTIVE_APPROVAL=elicitation rather than auto: a client that implements elicitation still asks you, and one that does not refuses the destructive tools outright instead of waiting on a page nobody can reach. Run the server natively when you want the loopback route.

An empty TELEGRAM_ALLOWED_CHAT_IDS grants the connector visibility across the whole selected Telegram account. Remote or model-facing deployments should set an explicit chat allow-list whenever the workflow has a narrower scope. The setting governs chat/message/folder data and chat-targeted side effects; it is not a complete account sandbox. Account, profile, and contact metadata tools remain controlled by account scopes, tool profiles, and MCP_TOOL_ALLOW / MCP_TOOL_DENY, so narrow those surfaces separately when required.

Audit summaries and JSONL records contain no argument values unless MCP_AUDIT_LOG_ARGS=true; when enabled, recognized credential fields are redacted. Set MCP_AUDIT_FILE to append forced JSONL records for a durable local trail. The directory is created automatically; symlink targets are rejected and POSIX files are restricted to their owner. Place the trail on a persistent encrypted volume and apply normal log retention and access controls.

The server never writes API hashes, bot tokens, 2FA passwords, auth codes, or MCP API keys to disk. Supply them through the environment or *_FILE mounted secrets. Secret files must be regular files (not symlinks), are size-limited, and may not be writable by group or others. Encrypt TDLib session storage at the OS/volume layer: BitLocker on Windows, FileVault on macOS, and LUKS/fscrypt or an encrypted volume on Linux.

Local state uses native OS paths by default: %LOCALAPPDATA%\\TelegramMcpServer on Windows, ~/Library/Application Support/TelegramMcpServer on macOS, and $XDG_DATA_HOME/telegram-mcp-server (or ~/.local/share/telegram-mcp-server) on Linux. Relative configured paths resolve below that location, not the current working directory.

Container images set TELEGRAM_MCP_DATA_DIR=/data/tdlib-data, which is backed by the compose volume. Set the same variable to an absolute encrypted volume path when running a multi-account server under another container orchestrator.

Tool responses may contain text, links and files written by other Telegram users. Treat that content as untrusted data in your MCP client or agent; do not let it override the client’s instructions. Prompt-injection policy belongs in that MCP host or agent because the connector does not interpret returned Telegram content as instructions. The server still enforces input-size limits and supports an optional operator-defined mcp.guardrails.blocked-patterns denylist.

transcribe_voice_note uses Telegram's own Premium/trial recognition feature. It never posts a new transcript message or uploads audio to a third-party service, but it can consume a Telegram recognition allowance and is therefore blocked in read-only mode and rate-limited.

Privacy, bot-command, and detailed group-permission writes are account-scoped, audited, and absent when MCP_READ_ONLY=true. Group-wide, member, and administrator permission changes are confirmation-gated when MCP_CONFIRMATION_REQUIRED=true; a group permission update preserves every flag the caller omits, while administrator-right updates intentionally replace the complete set and revoke omitted rights.

For remote deployment, terminate TLS before the service and restrict network access. See deployment modes and SECURITY.md.

Available MCP Tools

The full inventory is grouped below. In practice you start with a tool profile rather than enabling all of it at once.

Messages (29 tools)

Chats (45 tools)

configure_chat_folder intentionally sends a complete TDLib folder definition: when folder_id is supplied it replaces that folder's rules, rather than silently merging unknown state. list_chat_folders is populated from TDLib's account-folder update stream; call get_chat_folder for the complete rules of a known folder ID. Scheduled timestamps accept a future ISO-8601 instant or Unix epoch seconds; Telegram applies any product/account restrictions to repeating schedules.

Account Privacy & Bot Commands (4 tools)

set_privacy_settings intentionally replaces the selected setting's full rule set. It supports a base audience plus explicit users, chats, bots, and Premium-user exceptions; it does not mirror every raw TDLib setting. Bot command tools support Telegram's default, all-private, all-group, all-administrator, chat, chat-administrator, and chat-member scopes.

Users & Contacts (16 tools)

Media (7 tools)

Drafts (3 tools)

Public Search (3 tools)

search_public_messages does not guess a locale or apply a hidden product glossary. Supply query_variants for translations, synonyms, slang or likely typos. Interpret descriptions and pinned messages in the MCP host or product orchestrator, where locale-specific promotion and outreach policy can be configured without coupling it to the Telegram transport.

Meta (3 tools)

How to Add New Tools

1. Create a new class in src/main/kotlin/dev/telegrammcp/server/tool/:

@Component
class MyNewTool(
    private val telegramService: TelegramClientService,
    private val guardrailService: GuardrailService,
    private val objectMapper: ObjectMapper,
    private val meterRegistry: MeterRegistry,

) : McpToolHandler {

    override fun definition(): McpSchema.Tool = ToolSupport.definition(
        "my_new_tool",
        "Description of what this tool does",
        INPUT_SCHEMA,
        objectMapper,
    )

    override fun execute(
        exchange: McpSyncServerExchange,
        arguments: Map<String, Any>,
    ): McpSchema.CallToolResult {
        // Your logic here
    }
}

2. That's it. The tool is auto-discovered and registered on startup. McpConfig adds the safe account selector to account-bound tools automatically.

Project Structure

src/main/kotlin/dev/telegrammcp/server/
├── TelegramMcpApplication.kt          # Entry point
├── api/                                # Loopback-only interactive auth wizard endpoints
├── auth/                               # TDLib auth orchestration & runtime credentials
├── cli/                                # serve / auth / session / version commands
├── client/                             # Telegram client abstraction
│   ├── TelegramClientService.kt        # Telegram capability interface
│   ├── TdLibClientService.kt           # TDLib implementation
│   ├── TdLibConfig.kt                  # TDLib bean configuration & lifecycle
│   ├── TelegramAccountRegistry.kt      # Isolated multi-account routing
│   └── FallbackClientConfig.kt         # Fallback when TDLib unavailable
├── config/                             # Typed configuration properties & MCP wiring
│   ├── TdLibProperties.kt              # TDLib config (api, auth, database, session, proxy)
│   ├── McpSecurityProperties.kt
│   ├── ServerModeProperties.kt
│   └── McpConfig.kt                    # Tool registration, profiles, account selector
├── controller/                         # Well-known descriptor & OAuth metadata endpoints
├── model/                              # Domain models
│   ├── TelegramModels.kt
│   ├── EntityIdentifier.kt             # Sealed hierarchy: NumericId / Username / PhoneNumber
│   └── UserInfo.kt                     # UserInfo + ContactInfo
├── security/                           # Spring Security, API keys, account scoping
│   ├── SecurityConfig.kt
│   ├── ApiKeyAuthFilter.kt
│   ├── AccountAccessPolicy.kt
│   └── SecretResolver.kt               # *_FILE mounted-secret validation
├── service/                            # Business logic
│   ├── EntityResolverService.kt        # @username / +phone / ID resolution
│   ├── GuardrailService.kt             # Input limits & chat access
│   ├── OperationGuardService.kt        # Read-only & confirmation modes
│   ├── ToolSurfacePolicy.kt            # Tool profiles & allow/deny filters
│   ├── AntiSpamGuardService.kt         # Rate limits, daily caps, dedup
│   ├── AuditService.kt                 # Audit logging
│   └── FileSecurityService.kt          # File upload security
├── tool/                               # MCP Tools (auto-discovered)
│   ├── McpToolHandler.kt               # Tool interface
│   ├── message/                        # 29 message tools
│   ├── chat/                           # 49 chat, folder, permission & privacy tools
│   ├── user/                           # 16 user/contact tools
│   ├── media/                          # 7 media tools
│   ├── draft/                          # 3 draft tools
│   ├── research/                       # 3 bounded public-search tools
│   └── meta/                           # 3 manifest/account tools
├── util/                               # StructuredLogger, TextFormatter, MdcFilter
└── exception/                          # McpExceptions, GlobalExceptionHandler

Testing

# Unit tests
./gradlew test

# Specific test class
./gradlew test --tests "dev.telegrammcp.server.service.GuardrailServiceTest"

Contributing and Support

Read CONTRIBUTING.md before opening a pull request and CHANGELOG.md for release history. For a vulnerability, do not open a public issue; follow SECURITY.md. Community standards are in CODE_OF_CONDUCT.md.

Metrics

When Prometheus is enabled, metrics are available at /actuator/prometheus:

• mcp.tool.execution — tool execution duration by tool name

• mcp.audit.operations — audit counter by tool, category, outcome

• telegram.api.rate_limited — rate limiter rejections

• telegram.api.circuit_open — circuit breaker open events

• Standard Spring Boot / Micrometer HTTP metrics

License

Apache License 2.0