tg2codexMCP

A standalone Telegram MCP server for Codex, Cursor, Gemini CLI, Claude Code and Claude Desktop. It reads bot-received updates directly from the Telegram Bot API, retains a bounded local copy, and exposes tools for message retrieval, context, search and optional controlled sends. No n8n, workflow platform, LLM API or dot is required. The connected client performs analysis using its own model.

Status: locally tested implementation, not a live integration certification. The official MCP SDK client passes stdio and Streamable HTTP integration tests. Client-specific setup is based on official documentation; the five applications have not been configured or exercised against a live bot. See the verification matrix.

Quick start

Requires Node.js 24.x and npm. Build and test without credentials:

npm ci
npm run check

After approving use of a dedicated bot, copy .env.example to ignored .env, supply the bot token and allowed chat IDs, and set an absolute private DB_PATH. Keep sending disabled initially. Configure one client using an example and the client instructions. Each example launches Node directly; do not use npm start as the client's stdio command because npm can write non-protocol output to stdout.

The default is MCP_TRANSPORT=stdio and INGESTION_MODE=polling. The client starts/stops the process. INGESTION_MODE=offline reads retained data with no polling; an offline template needs no secrets. Polling starts on process launch and acknowledges Telegram updates, so do not enable it casually for a bot used elsewhere.

For multiple clients at once, run one HTTP connector with the HTTP template, then connect clients to http://127.0.0.1:8787/mcp with the configured bearer token. npm start is suitable for that foreground HTTP process. Never run several polling processes for the same bot, even with different databases. A database lock prevents accidental concurrent use of the same database.

Related MCP server: telegram-mcp-bridge

Tools

Read tools work independently of event subscriptions. Text is marked as untrusted data. Sends require ENABLE_SEND=true, a bot token, SEND_CHAT_IDS, confirmed=true and an idempotency key. HTTP also requires a separate send bearer credential. For stdio, access is granted by explicitly enabling writes for the locally launched process. Keep the host client's approval prompts enabled.

Ingestion and transports

• Direct long polling checks getMe and getWebhookInfo, then calls getUpdates. It never sets/deletes a webhook. An active webhook, authentication failure or polling conflict stops the service with a sanitized error.

• SQLite persists messages, edits, the polling checkpoint, optional event subscriptions/outbox and send results. Message storage and checkpoint advancement commit together. Disallowed-chat contents are discarded before retention.

• Standard MCP tools support legacy 2025 initialization and MCP 2 (2026-07-28) over stdio and Streamable HTTP through the official SDK. Legacy SSE-only endpoints are not implemented.

• Dot-specific webhook Events are an optional, disabled-by-default HTTP extension. They are not advertised to legacy clients. Ordinary clients discover tools without Events, callbacks or signing secrets.

Scope and limits

One configured owner and one bot per database; no personal-account login or complete historical archive. This receives only updates Telegram delivers to the bot. Text/captions and edits are retained; media download, deleted-message synchronization and topic filtering are not implemented. Retention defaults to seven days. Search has SQLite's ASCII case folding, not full Unicode normalization.

A standalone client gets tools, not an automatic background task in its conversation. Generic cross-client wake-ups are not implemented. Optional Events require a compatible client and separate live verification. HTTP is loopback-only with static bearer auth; public OAuth/multi-user deployment remains future work.

Read architecture, direct Telegram setup, security, operations and roadmap. Existing signed adapter ingress remains opt-in for advanced integrations; it is not used by the standalone setup.

License

Apache License 2.0, preserved from the original repository. Package publication is disabled by private: true; this does not change the source license.