dblokhin/tgcurl repository overview

⁠tgcurl — Telegram MCP server for AI agents (personal account)

tgcurl is a Telegram MCP server (Model Context Protocol) and JSON CLI for your personal Telegram account — not a bot. Built on the official TDLib, it lets AI agents and assistants like Claude Code, OpenCode and Codex read chats, search message history, send messages, files and photos, and track unread conversations through safe, paginated MCP tools: chats_list, chat_history, search_messages, send_message, send_file, send_photo, mark_read, contacts_list and more. Every response is clean JSON, service/system messages are filtered out, and the login session stays in a local Docker volume — nothing leaves your machine.

⁠Quick start

1. Log in once (interactive: phone, code, 2FA; the session persists in the tgcurl-data volume):

$ docker run -it --rm -v tgcurl-data:/data dblokhin/tgcurl login
$ docker run --rm -v tgcurl-data:/data dblokhin/tgcurl status
{"authorized":true,"user":{...}}

2. Add to your agent:

Claude Code

$ claude mcp add telegram -- docker run -i --rm -v tgcurl-data:/data dblokhin/tgcurl -mcp

OpenCode — add to opencode.json:

{
  "mcp": {
    "telegram": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-v", "tgcurl-data:/data", "dblokhin/tgcurl", "-mcp"]
    }
  }
}

Codex — add to ~/.codex/config.toml:

[mcp_servers.telegram]
command = "docker"
args = ["run", "-i", "--rm", "-v", "tgcurl-data:/data", "dblokhin/tgcurl", "-mcp"]

Then ask your agent: "check my unread Telegram chats and summarize them".

Source, CLI usage and design docs: https://github.com/dblokhin/tgcurl⁠

3. Example: