telegram-mcp

Why this one

Most Telegram integrations give a bot a token. A bot only sees the chats it was added to, cannot read your history, and can never act as you. This project connects an agent to your account instead, so its tools operate on the chats, contacts and messages you already have.

• Full account access. 72 tools spanning messages, chats, media, contacts, admin actions, session management, briefings, and search intelligence.

• Login without a terminal step. Credentials can be written by telegram_setup, and the first login happens entirely inside the chat — code and two-step password included.

• Access profiles. TELEGRAM_ACCESS_PROFILE=readonly|messaging|moderator|full limits which operations the server allows before any Telegram request.

• Human approval gate. TELEGRAM_APPROVAL_MODE=destructive|writes turns risky calls into one-shot approvals granted out-of-band (CLI or localhost dashboard).

• Local control center. telegram-mcp dashboard — a localhost-only web UI for policy, audit, approvals and tool catalog.

• MCP prompts & resources. 6 prompts and 4 resources (telegram://status, telegram://tools, telegram://audit/summary, telegram://security-model) for clients that support them.

• Workflow tools. telegram_briefing and telegram_search_intelligence compose low-level verbs into high-level tasks.

• One local process. stdio transport, no listening port, no cloud relay, no telemetry.

• Cross-platform. Linux, macOS and Windows. Paths are resolved with path; POSIX permissions go through a shim that is a no-op on Windows.

• Honest answers. Every state-changing tool reads the result back before reporting success. If Telegram accepted a call and ignored it, the tool tells you that instead of echoing the request.

Related MCP server: tlgrm

Quick start

npx -y @dikacode/telegram-mcp

That starts the server on stdio. In normal use you don't run it by hand: your MCP client spawns it. Add the server with one of the snippets in Connect your agent, restart the client, then ask the agent to log in.

If you would rather run from a checkout:

git clone https://github.com/dikaglorya/telegram-mcp.git
cd telegram-mcp
npm install
npm run build
cp .env.example .env
# add TELEGRAM_API_ID and TELEGRAM_API_HASH from my.telegram.org/apps
npm start

The server speaks MCP over stdio, so the last command is only a manual check. The code and the two-step password are typed in chat, never in a terminal.

Contents

• Quick start

• Architecture

• Requirements

• Install

• Updating

• Credentials

• First login — from chat

• Access profiles & human approval

• Local control center

• MCP prompts & resources

• Workflow tools

• Connect your agent

• Tools

• Security model

• Configuration

• Troubleshooting

• Development

• Project layout

• Release

• Reporting a bug

• Contributing

• License

• Contributors

Architecture

The agent spawns telegram-mcp as a child process and speaks JSON-RPC over stdin/stdout. The server holds one MTProto connection, signs in with a saved session, and translates each tool call into Telegram API requests. Nothing is exposed to the network: if the agent is not running, the server is not running.

agent  ── JSON-RPC / stdio ──▶  telegram-mcp  ── MTProto ──▶  Telegram
                                      │
                                      ├── ~/.telegram-mcp/session.txt   (0600)
                                      ├── ~/.telegram-mcp/audit.log     (redacted)
                                      ├── ~/.telegram-mcp/approvals.json (0600)
                                      ├── ~/.telegram-mcp/media/
                                      └── ~/.telegram-mcp/exports/

Three properties are deliberate:

1. The session file is the credential. It is written with mode 0600 and never returned by a tool. The api_hash is only used to create that session.

2. Tool output is data. Message text, names and files come from other people. The server labels untrusted content and never treats it as instructions; an agent should do the same.

3. Policy is enforced, not suggested. Access profiles and approvals are checked by the server before any Telegram request. An agent that hits PERMISSION_DENIED or APPROVAL_REQUIRED must tell the user — it cannot bypass the gate.

Requirements

• Node.js 20 or newer (22 LTS recommended).

• A Telegram account you can log into on your phone.

• An api_id and api_hash from my.telegram.org/apps. This is a one-time, free registration of a Telegram application.

• A supported MCP client: OpenCode, Claude Code, Codex CLI, Cursor, Windsurf, Claude Desktop, or anything that can spawn a stdio MCP server.

Install

Pick one path. All of them end with a telegram-mcp process that speaks MCP over stdio.

1. From npm

The package ships compiled JavaScript, so there is no build step and no compiler on your machine.

npx -y @dikacode/telegram-mcp

Or install it once, globally:

npm install -g @dikacode/telegram-mcp
telegram-mcp

npx is the shortest thing to put in an MCP client config:

{
  "command": "npx",
  "args": ["-y", "@dikacode/telegram-mcp"]
}

Pin a version if you want reproducible installs: npx -y @dikacode/telegram-mcp@1.1.0.

2. Clone and link

Best if you want to read the code, pin a commit, or modify a tool.

git clone https://github.com/dikaglorya/telegram-mcp.git
cd telegram-mcp
npm install          # also runs the build
npm link             # optional: makes `telegram-mcp` available on PATH

npm install runs the prepare script, which compiles dist/. If you edit the TypeScript later, run npm run build again.

3. Release tarball

Download the tarball attached to the latest release and install it globally:

npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.1.0/dikacode-telegram-mcp-1.1.0.tgz
telegram-mcp

The release tarball already contains the compiled dist/, so no build step is needed.

4. Unreleased commit from GitHub

Useful when you want a fix that has landed on main but is not in an npm release yet.

npx -y github:dikaglorya/telegram-mcp

npm fetches the repository, installs dependencies, runs the prepare build, and starts the launcher.

Updating

One command, whichever way it was installed:

telegram-mcp update

It works out how this copy got here and runs the right thing — npm install -g @latest for a global install (reusing a custom --prefix), git pull --ff-only plus a rebuild for a checkout, and a plain restart instruction for an npx run, where nothing on disk needs changing. --check reports and installs nothing.

telegram-mcp 1.1.0 · update

  installed   1.0.3  /home/you/.local/lib/node_modules/@dikacode/telegram-mcp
  latest      1.1.0
  install     global npm package

  ▲ 1.0.3 -> 1.1.0 available

Check what you are running:

telegram-mcp --version
telegram-mcp update --check                 # newer release available? installs nothing
npm outdated -g @dikacode/telegram-mcp      # global installs only

The server also tells you. When a newer release exists it prints one line to stderr at startup, after the MCP transport is already serving:

[telegram-mcp] update available: 1.0.3 -> 1.1.0. Run `npm install -g @dikacode/telegram-mcp@latest`, or set TELEGRAM_UPDATE_CHECK=0 to silence this.

That check is a single request to the npm registry with an 800 ms timeout, cached for 24 hours, and it never blocks startup or writes to stdout. If you want zero outbound traffic that is not Telegram itself, set TELEGRAM_UPDATE_CHECK=0. telegram_doctor shows the version it knows about without touching the network.

Credentials

1. Open my.telegram.org/apps and log in with your phone number.

2. Create an application if you do not have one. Any title and short name will do; platform can be Desktop.

3. Copy the api_id (a number) and api_hash (32 hex characters).

There are two ways to give them to the server.

A. Let the agent write them. If your MCP client already starts the server, ask the agent to call telegram_setup with the two values. The tool writes a .env next to the installed package, preserves any other keys already there, and never returns the hash.

{ "apiId": "1234567", "apiHash": "0123456789abcdef0123456789abcdef", "allowAllChats": true }

B. Pass them in the client config. This is the most reliable option for npx, because the npm cache can be replaced. Put them in the env / environment block of your MCP client — see the snippets below.

Never paste an api_hash into a chat message, an issue, or a screenshot. If one leaks, revoke the application on my.telegram.org and create a new one.

First login — from chat

You don't have to run a login command or answer a terminal prompt. The server starts unauthenticated, and the first tool call returns a structured NOT_AUTHORIZED error. The agent then drives the login:

1. telegram_login_start — sends a login code to your Telegram app. Pass phone in international format (or set TELEGRAM_PHONE beforehand).

2. telegram_login_code — you type the code to the agent in chat; the agent passes it to this tool.

3. telegram_login_password — only if two-step verification is enabled. Same rule: type it in chat, and the server will not echo or store it beyond the login.

4. The session is written to ~/.telegram-mcp/session.txt with mode 0600. Later runs skip the login entirely.

telegram_login_cancel abandons a half-finished login and forgets the code. Login codes and 2FA passwords are stripped from the audit log before they are written.

The server holds a code or password only for the duration of one call, but the agent's chat transcript is outside this project's control. If you would rather not put a 2FA password in that transcript, run npm run login in a terminal instead.

Windows: the session still lives under your user profile. NTFS inherits the profile ACL; the POSIX 0600 call is a documented no-op.

Access profiles & human approval

Access profiles

Set TELEGRAM_ACCESS_PROFILE in the MCP client environment to opt into a narrower profile. The default is full, so upgrading never silently removes a capability.

An invalid value fails closed to readonly and carries an explanation in telegram_permissions and telegram_doctor.

Human approval gate

Set TELEGRAM_APPROVAL_MODE to enable a one-shot approval step for risky calls. The server checks this before any Telegram request.

Flow:

1. Agent calls a write tool while approval mode is enabled.

2. Server hashes tool + canonical arguments, finds no approved record, stores a pending request, and returns APPROVAL_REQUIRED with an approval_id.

3. Human runs telegram-mcp approve <id> (or clicks Approve in the local dashboard).

4. Agent retries the exact same call; server consumes the approval once and executes it.

Approval records live in <state dir>/approvals.json (0600). Secret arguments are sanitized before storage; the hash is one-way (SHA-256). One approval = one execution. Denied approvals are final for that exact tool+arguments combination.

Optional TTL: TELEGRAM_APPROVAL_TTL_SECONDS (default 600, range 30–86400).

Quick reference

# Check current policy
telegram-mcp approvals

# Approve one exact call
telegram-mcp approve <approval-id>

# Deny one call (final for these exact args)
telegram-mcp deny <approval-id>

# Open the localhost dashboard
telegram-mcp dashboard

Local control center

telegram-mcp dashboard starts a localhost-only web server (127.0.0.1, random port) with a token-protected UI. It shows:

• Overview: access profile, approval mode, session presence, audit summary, pending approvals

• Approvals: pending requests with one-click Approve/Deny

• Audit log: filterable, paginated call log with outcome and error codes

• Tools: complete catalog with access profile, read-only/destructive hints

Security:

• Binds to 127.0.0.1 only, never 0.0.0.0

• Random 192-bit token, exchanged for HttpOnly; SameSite=Strict cookie (token removed from URL)

• Host header allowlist (DNS-rebinding defence)

• Strict CSP, no external assets, no CORS

• POSTs require X-Requested-With: telegram-mcp-dashboard header (CSRF defence)

• No session string, api_hash, or message content is returned by the API

# Default: random port, random token, prints one-time URL
telegram-mcp dashboard

# Fixed port / token (useful for scripts)
telegram-mcp dashboard --port 8787 --token my-secret-token-16chars

# Environment variables
TELEGRAM_DASHBOARD_PORT=8787
TELEGRAM_DASHBOARD_TOKEN=my-secret-token-16chars

The dashboard never opens an MTProto connection — live authorization checks stay in telegram_doctor.

MCP prompts & resources

The server registers 6 prompts and 4 resources for clients that support them (Claude Desktop, Cursor, etc.).

Prompts

Resources

Workflow tools

Two high-level tools compose the same policy checks, message shaping and read-back rules as the low-level verbs.

telegram_briefing

Read one or more chats and return a structured briefing:

• Activity per sender and per day

• Media counts (photos, documents, videos, etc.)

• Question candidates with whether they got a direct reply

• Recent highlights with links

• Most-viewed posts (channels)

• Extracted URLs

{
  "chats": ["@channel", "groupname"],
  "limit": 50,
  "since": "2026-10-01T00:00:00Z",
  "includeMessages": false
}

telegram_search_intelligence

Full-text search across selected chats (or every chat), grouped by person and chat:

• Matching messages with chat context

• Results grouped by sender and by chat

• Date range and media counts

• Optional filters: from (sender substring), mediaType, minDate/maxDate (unix seconds)

{
  "query": "quarterly budget",
  "chats": ["@finance", "@ops"],
  "limit": 20,
  "from": "alex",
  "mediaType": "document",
  "minDate": 1727740800,
  "maxDate": 1727827200
}

Both tools are readOnlyHint:true, policy-checked, and limited to 10 chats × 100 messages per call.

Connect your agent

The server is the same in every client; only the wrapper differs. Use the npx form unless you cloned the repository, in which case replace the command with node /absolute/path/to/telegram-mcp/dist/index.js.

OpenCode

opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "telegram": {
      "type": "local",
      "command": ["npx", "-y", "@dikacode/telegram-mcp"],
      "environment": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "0123456789abcdef0123456789abcdef",
        "TELEGRAM_ACCESS_PROFILE": "full",
        "TELEGRAM_APPROVAL_MODE": "destructive"
      },
      "enabled": true
    }
  }
}

Claude Code

claude mcp add telegram \
  -e TELEGRAM_API_ID=1234567 \
  -e TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef \
  -e TELEGRAM_ACCESS_PROFILE=full \
  -e TELEGRAM_APPROVAL_MODE=destructive \
  -- npx -y @dikacode/telegram-mcp

Or commit a project-scoped .mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@dikacode/telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "0123456789abcdef0123456789abcdef",
        "TELEGRAM_ACCESS_PROFILE": "full",
        "TELEGRAM_APPROVAL_MODE": "destructive"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.telegram]
command = "npx"
args = ["-y", "@dikacode/telegram-mcp"]

[mcp_servers.telegram.env]
TELEGRAM_API_ID = "1234567"
TELEGRAM_API_HASH = "0123456789abcdef0123456789abcdef"
TELEGRAM_ACCESS_PROFILE = "full"
TELEGRAM_APPROVAL_MODE = "destructive"

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@dikacode/telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "0123456789abcdef0123456789abcdef",
        "TELEGRAM_ACCESS_PROFILE": "full",
        "TELEGRAM_APPROVAL_MODE": "destructive"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json uses the same mcpServers shape as Cursor.

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Use the same mcpServers JSON as above, then restart the app.

Anything else

The contract is small: spawn a process, speak MCP JSON-RPC over stdio, pass the two required environment variables. If your client supports stdio MCP servers, it supports this one.

Tools

Every tool is strict about its arguments: an undeclared key is rejected instead of silently dropped, so a typo can never make a tool answer about the wrong chat. Names are stable; the table is the full list.

Account & session

Login

Chats & dialogs

Groups & channels

Messages

Media

Contacts & users

Audit

Workflows

A few behaviours worth knowing:

• Paging is explicit. History and search return hasMore plus a cursor (nextOffsetId, or nextOffsetRate for global search). Page two is not a guess.

• Reads before writes. pin_message, mute_chat, mark_read, delete_messages, clear_history and friends read the state back and report what actually changed.

• Errors carry a code and a hint. FLOOD_WAIT includes retryAfterSec; CHAT_ADMIN_REQUIRED names the missing right; NOT_AUTHORIZED tells the agent to start a login.

• Files stay local. download_media and export_history write under ~/.telegram-mcp/; delete_download cleans the index and, optionally, the file.

• Out of scope. Secret chats (end-to-end encrypted) and voice/video calls are not exposed by this server.

Security model

Full access is the default because that is the point of connecting your own account. The guardrails are there when you want them.

The allowlist and profiles are real gates, not display filters: every tool resolves its target through the same policy check, and the test harness probes all of them for bypasses (npm run test:policy).

Configuration

All settings are environment variables. The server also loads a .env next to the installed package, so telegram_setup works without touching your shell.

~ and ~\ are both expanded. Relative paths resolve against the current working directory.

Troubleshooting

Development

The repository ships with a unit suite and a real MCP harness that spawns the built server and calls tools over stdio.

npm install
npm run build

npm run test:unit          # 83 offline checks
npm run test:mcp           # read-only end-to-end pass
npm run test:mcp:write     # + self-cleaning writes
npm run test:destructive   # + disposable chats (opt-in, flood-limited)
npm run test:policy        # allowlist bypass probes
npm run test:access        # access profiles + approval flow (new)
npm run test:mcp -- --doctor

The end-to-end harness reads from a public channel by default. Point it at a chat you control for the full picture:

TELEGRAM_TEST_CHAT=@your_channel npm run test:mcp
TELEGRAM_HARNESS_CHAT=-1001234567890 npm run test:destructive

TELEGRAM_HARNESS_CHAT must be a chat the account administers; it enables the rename, invite-link and admin-list round trips. Without it those scenarios report an honest skip instead of a fake pass.

--destructive creates and deletes real groups and channels. Telegram flood-bans that aggressively. If a run hits FLOOD_WAIT, stop and wait; --cleanup and --reclaim exist for the debris an interrupted run can leave.

The harness also supports --json, --only=tool_a,tool_b, --cleanup, --reclaim, --allow=@chat, --deny=me and --doctor. See harness/README.md for the full behaviour, including how artifacts are verified and removed.

Project layout

telegram-mcp/
├── bin/telegram-mcp.js       portable launcher (finds Node, then dist/index.js)
├── cli/                      standalone login, doctor, update, dashboard, approvals
├── assets/                   animated README art (SVG, no scripts)
├── harness/                  unit checks + end-to-end MCP harness
├── docs/                     Jekyll site source (GitHub Pages)
├── integrations/             example configs for OpenCode, Claude Code, Codex, Cursor, VS Code, n8n
├── index.ts                  stdio entrypoint
├── server.ts                 tool registration
├── server-registry.ts        strict schemas, secret-arg scrubbing, tool guards
├── access.ts                 access profiles + tool classification
├── approvals.ts              human approval store (SHA-256, TTL, cross-process lock)
├── workflow-core.ts          pure aggregation logic (testable offline)
├── workflows.ts              telegram_briefing + telegram_search_intelligence
├── mcp-extras.ts             MCP prompts (6) + resources (4)
├── audit-read.ts             shared audit log parser + summarizer
├── audit-tools.ts            telegram_audit_log / telegram_audit_summary
├── audit.ts                  append-only audit log with secret redaction
├── config.ts                 env parsing, path resolution, memoized config
├── telegram.ts               GramJS client lifecycle (generation counter)
├── errors.ts                 RPC error normalization
├── perms.ts                  POSIX 0600/0700 with a Windows no-op
├── state.ts                  local state (allowlist + downloads, mtime-cached)
├── ui.ts                     terminal UI (spinner, steps, theming)
├── helpers.ts                chat resolution, message shaping, flood retry
├── version.ts                version + update check
├── package.json              metadata, scripts, mcpName
├── server.json               MCP Registry metadata (2025-12-11 schema)
└── tsconfig.json

The TypeScript is built with tsc to dist/. There is no bundler; the published package is the compiled tree plus the launcher.

Release

v1.1.0 is the current release, published to npm as @dikacode/telegram-mcp.

• 72 MCP tools (was 69), all registered with strict input schemas.

• Access profiles: readonly, messaging, moderator, full (default).

• Human approval gate: TELEGRAM_APPROVAL_MODE=destructive|writes with CLI + dashboard.

• Local control center: telegram-mcp dashboard (localhost-only, token/cookie auth, CSP, CSRF).

• MCP prompts (6) and resources (4): telegram://status, telegram://tools, telegram://audit/summary, telegram://security-model.

• Workflow tools: telegram_briefing, telegram_search_intelligence.

• Streaming downloads: telegram_download_media streams to disk, no OOM on large files.

• Memoized config + mtime-cached state for lower latency.

• Approval lock: exponential backoff, configurable timeout, read-only fast path.

• 83 offline unit checks (was 74).

• In-chat login, including two-step verification.

• Session file 0600, state directory 0700.

• Read-back verification for state-changing tools.

• Optional allowlist, audited calls, redacted secrets.

• Cross-platform launcher; no hardcoded paths.

• --version / --help, and a startup notice when a newer release exists.

• telegram-mcp update upgrades whichever layout is installed; --check reports without touching anything.

• End-to-end harness with paging, policy probes and artifact cleanup.

See CHANGELOG.md for the full release notes. Release artifacts are on the releases page.

Reporting a bug

Open an issue here: https://github.com/dikaglorya/telegram-mcp/issues/new/choose

You get two forms — Bug report and Feature request. The bug form asks for the version, install path, MCP client, OS, the tool involved, the error code, steps to reproduce, and telegram_doctor output. That is enough to reproduce most failures without a round trip.

If the server will not start at all, say so and paste the client's server log; the launcher prints one line explaining what is missing before it starts serving.

What not to put in an issue. Never include an api_hash, a session string, a login code, a 2FA password, your phone number, or the text of a private message. Chat ids and usernames of private chats should be redacted too. An issue is public and indexed the moment you submit it.

Security problems go private. Secret leakage, allowlist bypass, path traversal, session handling bugs, or a write tool that reports success without changing anything should go through GitHub's private advisory flow: Security → Advisories → Report a vulnerability (direct link: https://github.com/dikaglorya/telegram-mcp/security/advisories/new). That flow is enabled on this repository. SECURITY.md lists what is in scope and what is not — FLOOD_WAIT and account restrictions from automated behaviour are Telegram's, not vulnerabilities.

Before you report, the troubleshooting table already covers NOT_AUTHORIZED, FLOOD_WAIT, AUTH_KEY_DUPLICATED, CHAT_ADMIN_REQUIRED, PREMIUM_ACCOUNT_REQUIRED, a missing TELEGRAM_API_ID, and a missing dist/. A quick telegram_doctor call answers most "it will not connect" reports in one shot.

Contributing

Issues and pull requests are welcome. A useful PR is small, explains the failure it fixes, and includes a test that fails without it.

Before opening a PR:

npm run build
npm run test:unit
npm run test:mcp

Guidelines:

• Keep the strict-schema contract: a new tool declares every argument it accepts.

• A state-changing tool reads its result back; do not report the request as the outcome.

• Never log or return api_hash, session strings, login codes or 2FA passwords.

• Do not add a dependency when the standard library or an existing dependency already does the job.

• Match the surrounding style: two-space indent, explicit types at module boundaries, comments that explain why.

For a security issue, follow SECURITY.md. Do not open a public issue containing a session string, an api_hash or private message content.

License

MIT — see LICENSE.

Contributors

See CONTRIBUTORS.md for the canonical list. Contributions are credited in the release notes for the version that includes them.