dotiphant

Integrations

A local Telegram MCP server for your AI assistant

Dotiphant is an open-source MCP server for your own Telegram chats. It keeps a read-only archive of your chats in one file on your computer and gives your AI assistant tools to search and read it. It never sends, edits or deletes anything in Telegram.

Claude Desktop, Claude Code, Codex and Cursor start it on your computer. ChatGPT and claude.ai reach it through a tunnel you run.

Why a local archive, and not a bot

MCP (Model Context Protocol) is how AI apps call outside tools. A Telegram MCP server could talk to Telegram live on every question, or it could use a bot. Both have limits. A bot is a separate Telegram identity: it only sees messages sent after it joined a group, never the history, and it cannot read your private chats.

Dotiphant logs in as your own account, the way Telegram Desktop does, and copies your chats into a SQLite file on your computer. The MCP server reads that file. So your assistant sees the full history of every chat you are in, searches run fast, and answering a question sends no request to Telegram at all.

What your AI app can do with it

The server gives your AI app these tools:

  • list_chats: the chats in your archive, most recently active first, with message counts.
  • search_messages: full-text search across all chats, or one chat, a sender or a time range.
  • get_messages: read a chat, or the part of it around a message.
  • recent_activity: what happened in your chats recently.
  • chat_info: the title, username, forum topics and participants of one chat.
  • refresh: fetch new messages from Telegram. It still only reads, and runs at most once a minute.

All tools are read-only. There is no tool to send, edit, delete, forward or react, so even a confused or tricked assistant cannot act in Telegram through Dotiphant.

Set it up

  1. Install Dotiphant and run the setup. It opens in your browser and takes about five minutes: create your own free API id at my.telegram.org, scan a QR code with the Telegram app, choose what to archive, and run the first sync.
    curl -fsSL https://dotiphant.com/install.sh | sh
  2. Connect your AI app. Without a name, dotiphant connect lists the apps it can connect and whether it found them.
    dotiphant connectdotiphant connect claude-desktop  # or claude-code, codex, cursor, all
  3. Quit the AI app completely and start it again. On macOS that means Cmd+Q, not just closing the window.
  4. Ask a question, like "What did Clara and I agree on about the launch date?"

If an app is not found, dotiphant connect NAME --print prints the configuration to add by hand. The server itself is dotiphant mcp. Your AI app starts it as a child process over stdio, so nothing listens on your network.

Apps that only reach the internet

ChatGPT and claude.ai on the web and phone only talk to MCP servers on the internet over HTTPS. For them, run dotiphant mcp --http behind an HTTPS tunnel you run, such as ngrok, Tailscale Funnel or Cloudflare Tunnel. Each app has to be approved by you, in your terminal or with a one-time pairing code. See Connect Telegram to ChatGPT and the full remote access docs.

Limits worth knowing

  • The AI provider sees the messages its assistant reads to answer you: text, sender names, chat names and dates. That is how any connector works. Only connect apps whose provider you trust with your chats.
  • Messages are handed to the AI marked as untrusted content, and the AI is told not to follow instructions inside them. This lowers the risk of prompt injection. No tool can rule it out.
  • Secret chats are not included. They never reach Telegram's servers in readable form.
  • Channels are off by default. You can turn them on in the setup.
  • Dotiphant is an independent, unofficial project that uses the public Telegram API with your own API id. It is not made, endorsed or supported by Telegram.

More about what is stored and who can reach it: Security and privacy.

Install Dotiphant

Free and open source (MIT). macOS and Linux; Windows experimental. The command installs the latest GitHub release and opens the setup in your browser. It takes about five minutes.

The script is about 150 lines. Read it first, or see other ways to install. The installer verifies the download against the release checksums (SHA256SUMS) before installing. You can check signed build provenance with gh attestation verify; see Verify a download.

curl -fsSL https://dotiphant.com/install.sh | shdotiphant open  # setup opens in your browser

Updated . Something wrong or unclear? Open an issue.