agentforge-telegram-gateway

AgentForge Telegram Gateway

Connect user-owned AI agents to people through Telegram for notifications, conversations and file exchange.

Community Edition · MVP/Beta · GNU AGPL v3 (AGPL-3.0-only)

Quickstart · Features · MCP · Security · Architecture · Contributing

AgentForge Telegram Gateway is for developers and operators who want a small, self-hosted bridge between Telegram and local or remote AI-agent workflows. Pair a Telegram chat once, provision a source-scoped agent identity, then exchange text, documents and photos without putting a Telegram chat ID or bot token into agent prompts.

It works with MCP-capable clients and agent workflows such as ChatGPT, Codex, Claude and Qwen. The gateway is provider-independent: provider-account authentication remains with the provider's own tooling.

Quickstart

1. Install

git clone https://github.com/AgentForge-Labs/shared-telegram-notifier.git
cd shared-telegram-notifier
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

This installs four commands:

agentforge-telegram          inbox, reply, file and notification CLI
agentforge-telegram-mcp      MCP diagnostics and tool access
agentforge-telegram-admin    bot setup, source provisioning and pairing
agentforge-telegram-gateway  gateway server

2. Create a Telegram bot

Create a bot with Telegram's @BotFather, then store the token through the protected setup flow:

sudo agentforge-telegram-admin telegram-setup
sudo agentforge-telegram-admin telegram-doctor

The bot token is entered through a hidden prompt and stored outside the repository. Do not commit bot tokens, chat IDs or generated source credentials.

3. Provision and pair an agent source

sudo agentforge-telegram-admin provision my-agent \
  --output /var/lib/my-agent/telegram-gateway-key \
  --owner my-agent:my-agent

sudo agentforge-telegram-admin pair my-agent

Open the generated Telegram deep link. The pairing flow learns the authorized Telegram identity from Telegram itself; users do not need to copy a numeric chat ID.

4. Run the gateway

A hardened systemd unit is included at deploy/telegram-notifier.service. After installing the service and configuration paths for your host:

sudo systemctl daemon-reload
sudo systemctl enable --now telegram-notifier
curl http://127.0.0.1:8818/health

The gateway defaults to loopback. Put a TLS reverse proxy in front of it if an MCP client must connect remotely.

Features

• one-time Telegram pairing links — no manual chat-ID discovery;
• bidirectional text messages;
• inbound and outbound documents/photos;
• per-source receive, send and files permissions;
• multiple agent sources with isolated credentials and bindings;
• Telegram commands such as /agents, /use, /status and /help;
• REST/agent CLI for inbox, replies, files and proactive notifications;
• Streamable HTTP-style MCP endpoint;
• Bearer authentication for header-capable MCP clients;
• URL-secret mode for clients that cannot send custom authorization headers;
• OAuth 2.1 Authorization Code + PKCE for OAuth-capable MCP clients;
• source-scoped authorization so one agent credential cannot impersonate another source;
• loopback-first deployment and protected file-based secrets.

MCP access

The MCP gateway exposes the Telegram bridge to MCP-capable clients while preserving source isolation.

Bearer

Use the normal MCP endpoint with the source credential:

POST https://telegram.example.com/mcp
Authorization: Bearer <source-secret>

URL secret

For clients that cannot attach an authorization header:

https://telegram.example.com/client/<source-secret>/mcp

Treat that URL as a credential. Configure reverse-proxy access logs so the secret-bearing path is never recorded verbatim.

OAuth + PKCE

OAuth-capable MCP clients can use the gateway's protected-resource and authorization-server discovery endpoints with Authorization Code + PKCE S256. Configure OAuth with protected secret files; do not place client secrets directly in committed service files.

See docs/ARCHITECTURE.md for the authentication and trust boundaries.

Generate an MCP connection file

The admin CLI can write a protected client configuration without printing the source secret to standard output:

sudo agentforge-telegram-admin mcp-config my-agent \
  --provider qwen \
  --base-url https://telegram.example.com \
  --key-file /var/lib/my-agent/telegram-gateway-key \
  --output /var/lib/my-agent/telegram-mcp.json \
  --owner my-agent:my-agent

Use the provider value that matches the client you are configuring. Generated connection files are credentials and should remain outside the repository.

Agent CLI examples

Check the authenticated inbox:

agentforge-telegram --help

The CLI supports receiving events, replying, retrieving inbound files and sending notifications. Run --help for the current command surface rather than copying credentials into shell history.

Python SDKs

The REST client is importable directly after installing the PyPI package:

from agent_client import TelegramAgentClient

client = TelegramAgentClient.from_key_file(
    "my-agent", "/var/lib/my-agent/telegram-gateway-key"
)
events = client.inbox(limit=10)

For MCP transport diagnostics and arbitrary tool calls, use mcp_client.TelegramMcpClient or the matching CLI command:

agentforge-telegram-mcp --base-url https://telegram.example.com \
  --auth bearer --key-file /var/lib/my-agent/telegram-gateway-key call \
  telegram_inbox --arguments '{"limit":10}'

Security

The project is designed around a simple rule: Telegram identity, gateway identity and model-provider identity are separate trust boundaries.

Key defaults and protections include:

• gateway TCP bind defaults to 127.0.0.1:8818;
• the bot token lives in a protected file outside the repository;
• source credentials are generated per agent/source;
• persistent registries store credential digests rather than plaintext source keys;
• pairing codes are short-lived and one-use;
• OAuth uses exact redirect-URI matching and PKCE S256;
• OAuth authorization/access/refresh state is stored as digests where applicable;
• URL-secret application logs are redacted;
• audit metadata excludes message text, file contents and raw credentials;
• group chats are disabled by default.

Example configuration lives in .env.example and contains placeholders/file paths only. Never commit a real bot token, numeric personal chat/user identifier, real conversation fixture, private webhook URL or generated agent credential.

For trust boundaries and protocol flow, see docs/ARCHITECTURE.md. For vulnerability reporting, see SECURITY.md.

Deployment notes

The included systemd unit is a reference for Linux hosts. Review service user/group ownership and paths before enabling it on your system. Remote MCP access should use HTTPS at the reverse proxy; do not expose the loopback HTTP listener directly to the public internet.

Useful diagnostics:

agentforge-telegram-admin telegram-doctor
agentforge-telegram-mcp --help
agentforge-telegram-gateway --check

What this project is — and is not

This repository is the focused Telegram communication bridge. It does not contain the AgentForge cloud control plane, private AgentScope backend, enterprise infrastructure orchestration or production credentials.

For broader AgentForge projects and public releases, visit AgentForge Labs on GitHub.

Within the AgentForge product family:

• AgentScope is the natural next step when you need observability and operations around agent runs;
• AgentForge Runtime is the commercial expansion when you need controlled infrastructure access and enterprise runtime capabilities.

No private repository is required to use this Community Edition.

Contributing

See CONTRIBUTING.md. Please keep examples synthetic and never include real Telegram credentials, personal chat/user IDs or customer messages in issues, fixtures or pull requests.

License

AgentForge Telegram Gateway Community Edition is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE.

Maintainers

Maintained by AgentForge Labs.

Commercial web application

The private commercial repository includes a separate Next.js marketing and checkout app in web/.

cd web
npm ci
npm run validate
npm run dev

Payment credentials and provider product/variant IDs are documented in web/.env.example. They are server-side only.