NetGram

The Telegram MCP that doesn't YOLO your account.

A self-hosted bridge that gives an AI agent scoped, permissioned access to your Telegram — you decide, per chat, what it may read and write, and every outgoing message or button click needs your approval before it hits Telegram. Runs locally in Docker with a small web UI to manage access.

Most Telegram MCP servers log in as a userbot and hand the AI full access to everything — all your DMs, groups and channels, with send rights. NetGram is the opposite bet: least-privilege by default, human-in-the-loop for anything that leaves your account.

Why NetGram

The whole idea: an agent can read the chats you picked and propose actions, but you stay the one who presses send.

Related MCP server: agent-telegram-mcp

Quick start (Docker)

git clone https://github.com/<you>/netgram.git
cd netgram
docker compose up -d --build

Open http://localhost:3000 and follow the setup screen:

1. Paste your own api_id / api_hash from my.telegram.org/apps and your phone — nothing to edit in files, it's stored locally in ./data.

2. Enter the Telegram login code (and 2FA password if you have one).

Then open /permissions and switch on the chats the AI may touch.

All state (credentials, session, allowlist, drafts) lives in the ./data volume, so it survives restarts and rebuilds.

Use it from your AI (MCP)

NetGram ships a Model Context Protocol server (mcp/server.mjs) so any MCP client — Claude Desktop, Claude Code, Cursor, Cline — can drive it. Install deps once, then point your client at the server:

npm install   # once, for the MCP server's dependencies

{
  "mcpServers": {
    "netgram": {
      "command": "node",
      "args": ["/absolute/path/to/netgram/mcp/server.mjs"],
      "env": { "NETGRAM_BASE_URL": "http://localhost:3000" }
    }
  }
}

Tools exposed (deliberately read + propose only):

Notably absent by design: there is no tool to grant permissions or to approve/send a draft. Those are human-only, in the web UI. So the worst an AI can do is read chats you allowed and pile up drafts you can ignore.

Prefer curl or a Claude Code skill? The same actions are available over the raw HTTP API.

Permission model

One escalating level per chat (full ⊃ write ⊃ read), set by you on /permissions:

full is your explicit opt-in to autonomy for a specific chat. Everything is enforced server-side — a request outside the allowlist never reaches Telegram.

How it works

AI (MCP client) ──stdio──▶ mcp/server.mjs ──HTTP──▶ NetGram (Next.js)
                                                    │  allowlist gate (per chat)
you (browser) ──────────────────────────────────▶  │  drafts + approval
                                                    └─ GramJS / MTProto ─▶ Telegram

• Next.js app: web UI (/permissions, /drafts) + HTTP API.

• GramJS (MTProto): logs in with your account and session.

• MCP server: thin, safe bridge over the HTTP API for AI clients.

• State in ./data: config.json (creds), session, allowlist.json, drafts.json — all git-ignored.

Safety & caveats

• Self-hosted, single-user. You run it on your own machine with your own Telegram app credentials. Nothing is shared with a third party.

• MTProto userbot = ToS gray area. Like every "userbot" tool, this logs into your account via MTProto, which Telegram's ToS doesn't officially bless — there is a non-zero account-ban risk. Use a burner/secondary account if that worries you. This is true of all Telegram MCPs; NetGram just doesn't hide it.

• Approval is the safety net. Drafts require a deliberate click, and the confirm dialog's prominent button is Cancel — an accidental (or automated) single click cancels rather than fires.

• Don't grant full unless you mean it. It removes the approval step for that chat.

Run without Docker (dev)

npm install
npm run dev          # http://localhost:3000, state in ./data

Power users can skip the setup screen by providing creds via env instead (.env with TG_API_ID / TG_API_HASH / TG_PHONE); env takes precedence over the wizard.

API

License

MIT — see LICENSE.