tgfmcp

tgfmcp is an open-source Telegram stdio MCP server built on top of telegraf, commander, and @modelcontextprotocol/sdk.

It lets MCP-compatible clients interact with the Telegram Bot API through Telegraf and optionally subscribe to incoming Telegram events through an MCP notification channel.

Highlights

• Exposes Telegram as an MCP server over stdio.
• Uses telegraf directly for polling and Bot API operations.
• Supports interactive configuration via tgfmcp configure.
• Provides direct Bot API tools for bot identity and chat lookups.
• Includes mutating tools for sending, replying, reacting, editing, deleting, forwarding, and typing.
• Can emit incoming message events over an optional MCP notification channel.
• Stores downloaded incoming media attachments under ~/.tgfmcp/attachments/.

Requirements

• Node.js 24+
• A Telegram bot token

Installation

Use it without installing globally:

npx tgfmcp mcp

Or with Bun:

bunx tgfmcp mcp

If you prefer a global install:

npm install -g tgfmcp

For local development:

npm install
npm run build
npm run dev -- mcp

Quick Start

1. Run the interactive configuration:

tgfmcp configure

This writes:

~/.tgfmcp/config.json

2. Start the MCP server:

npx tgfmcp mcp

3. If your MCP host supports notifications and you want incoming Telegram events, enable channels:

npx tgfmcp mcp --channels

The server uses stdio, so it is meant to be launched by an MCP client or wrapper rather than browsed directly in a terminal.

CLI Usage

MCP Server

npx tgfmcp mcp
bunx tgfmcp mcp

Starts the stdio MCP server for the configured Telegram bot.

Configure

npx tgfmcp configure

Then opens an interactive configure UI (Ink) to manage:

• Bot token
• Allowed users
• Allowed chats

Allowlist items are toggled from menu screens (select an entry to toggle it, then choose Back).

For enrolling users/chats, configure can generate a short code per screen and watch incoming Telegram updates. Send the code from the target user/chat and the matching ID is auto-added to allowlist.

Everything is persisted to:

~/.tgfmcp/config.json

MCP Tools

The server currently exposes these tools:

• telegram_get_me
• telegram_get_status
• telegram_get_chat
• telegram_get_chat_administrators
• telegram_lookup_chat
• telegram_send_message
• telegram_send_media_from_base64
• telegram_send_media_from_path
• telegram_reply_to_message
• telegram_react_to_message
• telegram_edit_message
• telegram_delete_message
• telegram_forward_message
• telegram_send_typing

Push Channel

When started with --channels, the server:

• advertises the experimental MCP capability hooman/channel
• advertises hooman/user with path meta.user
• advertises hooman/session with path meta.session
• advertises hooman/thread with path meta.thread
• advertises hooman/channel/permission for remote daemon approvals
• emits notifications/hooman/channel for incoming Telegram message events

If allowlist entries are configured, notifications/hooman/channel events are emitted only when either:

• meta.session (chat ID) is in allowlist.chats, or
• meta.user (sender user ID) is in allowlist.users

When no allowlist is configured (or both arrays are empty), all inbound channel events are emitted.

Each notification includes:

• content: a JSON-encoded event payload
• meta.source: always telegram
• meta.user: the sender identity seed for the incoming message
• meta.session: the chat identity seed for the incoming message
• meta.thread: the Telegram message ID for the incoming message

The JSON-decoded content payload includes:

• source
• self
• message
• text

If an incoming message contains downloadable media, the file is downloaded and included as a local attachment path in the event payload. Files are stored under ~/.tgfmcp/attachments/.

When Hooman sends notifications/hooman/channel/permission_request, tgfmcp posts the request back into the originating Telegram chat with inline approval buttons from params.options. Button selections are relayed back over notifications/hooman/channel/permission.

Approvals are handled through inline buttons rendered from the permission request options.

Local Data

tgfmcp stores local state under ~/.tgfmcp/:

• config.json for bot token and allowlist
• attachments/ for downloaded incoming media attachments

Notes

• Telegram bots cannot access arbitrary private chats; they can only interact where the bot has been added, contacted, or is otherwise permitted.
• Message mutation tools that target an existing message require explicit chatId and messageId inputs.

License

MIT. See LICENSE.