Local Setup

Get a working dev environment from a fresh clone.

Prerequisites

Tool	Version
Node.js	20+ (matches `engines.node` in `package.json`)
Docker	for the local Postgres container
A Telegram bot token	from @BotFather — needed to actually exercise the webhook end-to-end

Windows: the project develops fine on Windows + PowerShell (the maintainer’s host). The Bash tool is also available via WSL or git-bash if you prefer POSIX commands.

First-run steps

Clone + install


git clone <repo> telegram-mcp
cd telegram-mcp
npm ci

Env file


cp .env.example .env
# Fill in TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, ADMIN_TELEGRAM_USER_ID
# The other secrets can stay blank until the phase that needs them.

Generate random 32-byte secrets:


node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Postgres
```
npm run db:up        # docker compose up -d
npm run migrate      # node-pg-migrate up
```
Connection string defaults match the docker-compose service; if you point at a different DB, update DATABASE_URL in .env.
Run the test suite
```
npm test
```
All unit tests should pass. The users.repo.test.ts suite requires a running Postgres + migrations — without them, it self-skips with a clear error message (“Run npm run db:up && npm run migrate before npm test”).
Start the server
```
npm run dev
```
Should log admin bootstrapped then Server listening. Hit /healthz:
```
curl -sf http://127.0.0.1:3000/healthz
# → {"ok":true}
```

End-to-end with Telegram

The webhook needs a public HTTPS URL. Two approaches:

Tunnel from local (fastest iteration): ngrok http 3000 (or cloudflared tunnel). Set PUBLIC_BASE_URL to the tunnel URL, then npm run register-webhook. Send /start to the bot.
Deploy to the VPS: see ops/deploy.md.

Useful commands

Task	Command
Run dev server with auto-reload	`npm run dev`
Run tests	`npm test`
Watch tests	`npm run test:watch`
Coverage	`npm run test:cov`
Typecheck	`npx tsc --noEmit`
Lint	`npm run lint`
Format	`npm run format` (or `npm run format:check`)
Up/down DB	`npm run db:up` / `npm run db:down`
Migrate	`npm run migrate` / `npm run migrate:down`
Register Telegram webhook	`npm run register-webhook`

Common issues

connect ECONNREFUSED 127.0.0.1:5432: Postgres isn’t running. npm run db:up.
relation "users" does not exist: migrations haven’t been applied. npm run migrate.
Telegram replies are silent after /start: webhook isn’t registered at the URL the bot’s actually reachable at. Re-run npm run register-webhook after changing PUBLIC_BASE_URL.