tolboy/telegram-mcp-tdlib
Developer toolsЭта страница переведена автоматически. Технические детали смотрите в оригинале. Открыть оригинал
TDLib-powered Telegram MCP server for JVM/Kotlin. Full client access for AI agents.
Обзор
A local-first Model Context Protocol server that gives an AI agent real Telegram-account access without handing it the keys to your account. It starts read-only, hides write tools until you opt in, and runs over for desktop clients or at /mcp for managed deployments. - — boots in read-only mode with a small inbox/reader profile; write and quota-consuming tools are hidden from the model, not merely blocked, until you turn them on. - — destructive tools ask a person first: through the MCP host where elicitation exists, otherwise on a single-use loopback page this server hosts. Either way the question leaves and the answer returns outside the model's turn, so an injected instruction can make the model request a ban, not approve one. - — an idempotency_key turns a lost response into a stored receipt instead of a duplicate message; an unconfirmed send is reported as UNKNOWN, never silently resent.
README
Показан фрагмент оригинального README. Открыть оригинал.
Telegram MCP Server
Telegram MCP for real accounts — safe by default, TDLib-powered, production-ready.
A local-first Model Context Protocol server that gives
an AI agent real Telegram-account access without handing it the keys to your account. It
starts read-only, hides write tools until you opt in, and runs over STDIO for desktop
clients or Streamable HTTP at /mcp for managed deployments.
Why this one?
- Safe by default — boots in read-only mode with a small
inbox/readerprofile; write and quota-consuming tools are hidden from the model, not merely blocked, until you turn them on. - Human approval that does not depend on your client — destructive tools ask a person first: through the MCP host where elicitation exists, otherwise on a single-use loopback page this server hosts. Either way the question leaves and the answer returns outside the model’s turn, so an injected instruction can make the model request a ban, not approve one.
- Sends an agent can retry — an
idempotency_keyturns a lost response into a stored receipt instead of a duplicate message; an unconfirmed send is reported asUNKNOWN, never silently resent. - Real user accounts, not just bots — built on TDLib (via tdlight-java), so an agent can read and act on your actual account, not only a Bot API subset.
- Isolated multi-account — each account gets its own session, mandatory selection, and scoped API keys; reads never fan out across accounts.
- Two transports — STDIO for Claude Desktop / Cursor / VS Code / Codex, Streamable HTTP for a managed service.
- No JDK to install — runtime-inclusive release bundles for Windows, Linux x64/ARM64, and Apple-silicon macOS, with checksums, an SBOM, and signed container digests.
The image is an illustrative mockup; a real screencast is on the way.
Safe first run
Runtime-inclusive releases need no JDK, Gradle, Git, Python, or Node.js. Use a test account for your first run if you can.
1. Install (macOS Apple silicon / Linux with Homebrew):
brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb
Windows with Scoop:
Установка
docker run --rm -p 127.0.0.1:8080:8080 \Конфигурация
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp",
"args": ["serve", "--transport", "stdio"],
"env": {
"TDLIB_API_ID": "123456",
"TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
"MCP_TOOL_PROFILE": "inbox",
"MCP_READ_ONLY": "true"
}
}
}
}