mtcute - v0.16.0

mtcute logo

modern typescript library for mtproto
documentation  •  api reference  •  telegram chat

NodeJS CI tl layer npm alpha version

[!WARNING] mtcute is currently in alpha stage: the api is not very stable yet, and there may be a lot of bugs
feel free to try it out, though, any feedback is appreciated!

releases may not follow semver just yet, so please pin the versions for now

import { TelegramClient } from '@mtcute/node'
import { Dispatcher, filters } from '@mtcute/dispatcher'

const tg = new TelegramClient({
apiId: parseInt(process.env.API_ID),
apiHash: process.env.API_HASH,
storage: 'my-account'
const dp = Dispatcher.for(tg)

dp.onNewMessage('private'), async (msg) => {
await msg.replyText('hiiii from mtcute! 🌸')
}){ /* optional params */ }, async (self) => {
console.log(`✨ logged in as ${self.displayName}`)

mtcute is a modern, performant and ✨ cute ✨ mtproto library and bot framework, supporting both web and nodejs.

quick start

🤖 just starting a (user)bot? use the scaffolding tool:

pnpm create @mtcute/bot

🏭 want to integrate it into your existing nodejs app? use the nodejs package:

pnpm add @mtcute/node
# optional, for faster crypto
pnpm add @mtcute/crypto-node

✨ building something for web? use the web package:

pnpm add @mtcute/web

🚀 using the newfangled runtimes? we've got you covered:

  • bun: bun add @mtcute/bun
  • deno: import { TelegramClient } from 'jsr:@mtcute/deno'

learn more: guide


  • 🍰 simple: mtcute hides all the complexity and provides a clean and modern api
  • compatible: mtcute supports almost everything bot api does, and even more!
  • 🍡 lightweight: running instance uses less than 50 mb of ram
  • 🛡️ type-safe: most of the apis (including mtproto) are strictly typed to help your workflow
  • ⚙️ hackable: almost every aspect of the library is customizable, including networking and storage
  • 🕙 up-to-date: mtcute uses the latest TL schema to provide the newest features as soon as possible

cat in the readme 🐈

project goals

mtcute strives to:

  • be customizable enough to fit most of the possible use-cases
  • be lightweight, both in terms of runtime and bundle size
  • support (theoretically) any environment without much hassle
  • provide a solid foundation for all kinds of applications on telegram platform
  • provide a convenient high-level api for the most commonly used features

mtcute is NOT and will never be:

  • a library for spam/flood or otherwise malicious activities
  • a fully feature-complete library - highlevel apis will never cover the entirety of the apis. feel free to contribute, though!
  • a drop-in replacement for (insert library name)
  • a teapot

setting up for development

git clone
fnm use # or `nvm use`
cd mtcute
pnpm install --frozen-lockfile

# generate code from tl schema
pnpm -C packages/tl run gen-code


some parts were based on or greatly inspired by these projects:

Generated using TypeDoc