基于个人 Telegram 账户的 MCP 服务器：79 个工具，MTProto，不是 Bot API。
它是什么。 tg-mcp 让 MCP 客户端（Claude Code、Claude Desktop 或任何支持 MCP 的程序）能够访问你的个人 Telegram 账户：阅读任意聊天、搜索全部历史、查看照片、收听语音消息、以你的身份发送消息、管理群组和论坛。它通过 Telethon 使用 MTProto 协议，不是 Bot API，因此它看到的是整个账户，而不仅仅是发给机器人的消息。
工作原理。 一个守护进程持有 Telegram 会话并完成所有工作；MCP 服务器是一个轻量级的 stdio 进程，通过 unix socket 将调用转发给它。即使没有 agent 在运行，同一个守护进程也在工作：将收到消息的提醒发送到你自己的 bot，按计划生成摘要，收件箱过滤器和提醒。由于使用 unix socket，支持的系统是 macOS 和 Linux——在 Windows 上请使用 WSL 或 Docker。
快速开始（需要 Python 3.11+ 和 uv）：
git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg init # one wizard: keys, login, bot, daemon, MCP registration, subagentstg init 只询问缺失的内容，因此重复运行是安全的，也可以用来修复安装。只有 API 密钥和登录本身是必需的——其他所有内容都可以按 Enter 跳过，向导会说明缺少每一项会导致哪些功能不可用。登录验证码和 2FA 密码由你自己输入，并且永远不会被存储。uv run tg doctor 会输出现有安装的状态。
运行之前。 这是一个个人工具，不是托管服务，它持有一个真实账户。data/session.session 可以在没有密码和 2FA 的情况下完全访问该账户；本地索引和按聊天整理的文件会将消息文本写入磁盘；档案功能会将聊天内容发送到外部模型。请先阅读 SECURITY.md——它很短。
费用是多少。 默认情况下免费。两个可选功能可能产生费用：每个聊天的档案会调用外部模型，按 token 计费——在你启用之前处于关闭状态，启用后每小时有上限；Groq 转录只在速率限制内免费。Telegram 自带的转录需要 Premium，而本地 Whisper 模型消耗的是磁盘和 CPU，而不是金钱。
当出现问题，先从 uv run tg doctor 和 docs/troubleshooting.md 开始。
其余文档为俄语： docs/tools.md（每个工具）、docs/architecture.md、docs/configuration.md、docs/mcp.md、docs/troubleshooting.md、docs/security.md。采用 MIT 许可证。
Related MCP server: mcp-telegram
这是对个人 Telegram 账户的封装，将其作为一组 MCP 工具提供给 agent。它基于 MTProto（Telethon）工作，而不是 Bot API——因此可以看到整个账户，而不仅仅是写给机器人的内容。这是一个面向单个账户和单一所有者的个人工具，而不是服务：它在你机器上保存着 Telegram 的实时会话，并以你的名义给真人发消息。
与 Bot API 封装的区别是根本性的，而不是数量上的。机器人只能看到发给它的消息，无法阅读与人的对话，没有历史记录，并且在有人按下 Start 之前并不存在。在这里，agent 拥有与你在应用程序中相同的访问权限：所有对话、搜索所有消息、附件、文件夹、草稿，以及以你的名义发送消息。这样做的代价是下面的「风险」一节，并且必须在运行前阅读，而不是之后。
agent 不仅能读取消息，还能查看图片（tg_view 直接返回图像）和收听音频：语音消息、视频消息、音乐和视频可以通过 Telegram 内置转录、Groq Whisper 或本地模型进行转写。长帖子由 Telegram 自己总结（tg_summarize），故事（stories）可以在不留下痕迹的情况下阅读，而 tg_wait 和 tg_ask 让 agent 能够等待特定消息或在 bot 中直接向所有者请求许可。
处理收到的消息不仅仅看未读：tg_pending 显示中断的对话——你未回复谁、谁未回复你，包括那些已被阅读但被遗忘的（未读计数中已经没有了）。tg_person 通过一次调用整理出一个人的档案：个人资料、标志、共同群聊、在聊天对象中的排名、以及个人聊天历史。tg_memory 维护一个关于聊天的持久档案，这样陌生的对话就不必从上千条历史消息开始。
守护进程还能做不需要启动 Claude 的事情：将重要收到的提醒发送到你的 bot，按计划生成摘要（digest_at），收件箱过滤器（标记为已读、归档、静音、移动到文件夹、添加到收藏）以及重启后仍然有效的提醒。过滤器操作中故意没有自动回复：规则在无人监督的情况下运行，不应能够给陌生人发消息。
对于所有者指定的聊天，会建立本地全文索引（tg_index，sqlite + FTS5）：这样 tg_search(engine="local") 可以立即搜索，并且能做到服务器端搜索完全没有的功能——按作者过滤、获取“某人某时间段内的全部消息”、按相关性排序并高亮匹配项。
完整参考—— docs/tools.md。
MCP-клиент (Claude Code, Claude Desktop, любой другой)
│ stdio
▼
tgagent.mcp_server ──unix socket──▶ tgagent.daemon ──MTProto──▶ Telegram
79 инструментов /data/daemon.sock │
├─ watcher: входящие → фильтры → алерт
├─ дайджест по расписанию
├─ напоминания и ожидание
└─ Bot API ──▶ твой бот ──▶ ты核心是 tgagent/core.py：一个 TelegramService 类，包含所有账户操作和所有保护措施。其他一切都是围绕它的传输层。详情：docs/architecture.md。
需要 Python 3.11 或更高版本以及 uv。唯一的要求是 datetime.UTC（3.11 的别名）；代码中没有使用 3.12 和 3.13 的特性。系统要求是 macOS 或 Linux：MCP 服务器通过 unix socket 与守护进程通信，因此不支持 Windows（在 WSL 或 docker 中可以运行）。
可以在任何目录下运行：项目路径是相对于其自身的，所有它输出的命令都已经包含了指向该副本的真实路径。
git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg inittg init 是一个向导，它会将安装引导到可工作状态：应用密钥、账户登录、通知 bot、守护进程、在 Claude Code 中注册 MCP 服务器以及 ~/.claude/agents 中的子 agent。每一步都会解释它的用途以及没有它时哪些功能将不可用。
关于这个向导，有三件事值得提前了解：
只有 api_id/api_hash 和登录是必需的。 bot、模型密钥、本地转录和自动启动都可以按 Enter 跳过。
Telegram 验证码和云端 2FA 密码由你输入。 向导不会请求、填入或存储它们——它会将这个步骤交给 tg login。
重复运行是安全的。 向导会首先检查已完成的内容，只做缺失的部分，因此也可以用作“帮我修复安装”。
途中需要的：my.telegram.org 上的应用 → API development tools（从中获取 api_id 和 api_hash；没有它们只能使用 Bot API，也就是说看不到自己的聊天），如果需要提醒，还需要在 @BotFather 处创建一个单独的 bot——不能复用已有的 bot，否则它的消息会成为你的收件消息，从而导致提醒叠加提醒。
在最后，向导会输出 tg capabilities：哪些功能可用，哪些被阻止，以及具体原因。uv run tg doctor 会检查已安装的状态——哪些组件存在、哪些在运行、文件位于何处以及权限如何、守护进程是否响应、MCP 是否注册、子 agent 是否与仓库一致。它的输出中没有密钥、电话号码和账户名称，因此可以完整地附加到 issue 中。如果运行后仍然有问题——请参阅 docs/troubleshooting.md：那里列出了常见问题，并以外部的视角描述。
向导本身不会做任何事——它调用的是同样的命令，其中任何一条都可以单独执行：
cp .env.example .env && chmod 600 .env
uv run tg setup # api_id/api_hash и токен бота, скрытым вводом
uv run tg login # телефон, код из Telegram, облачный пароль при 2FA
uv run tg link-bot # нажми Start в чате с ботом, команда запомнит твой chat_id
uv run tg daemon start # демон владеет сессией; без него инструменты не работают
uv run tg status # что настроено, что нет, живой ли демон
claude mcp add -s user telegram -- uv --directory "$PWD" run tg-mcp
cp agents/*.md ~/.claude/agents/接下来是 docs/mcp.md：作用域、Claude Desktop、现成的子 agent、诊断。提醒、过滤器和限额的设置——docs/configuration.md。
cp .env.example .env && chmod 600 .env # заполни TG_API_ID / TG_API_HASH / TG_BOT_TOKEN
docker compose build
docker compose run --rm tgagent tg login # логин интерактивно, сессия ляжет в ./data
docker compose up -d
claude mcp add telegram -- docker exec -i tgagent tg-mcp详细信息（包括为什么 MCP 在容器内运行而不是在宿主机上）—— docs/docker.md。
agent 本身是免费的，基础模式下不需要向任何人付费：MTProto、通知 bot、服务器端搜索、本地索引、提醒、摘要、过滤器和提醒都不花钱。费用可能出现在两个地方，而且两处都需要默认未提供的密钥：
聊天档案（tg_memory）会调用外部模型，按 token 计费——默认使用密钥 OPENAI_API_KEY 对应的 gpt-4o-mini。这是唯一会自动花钱的功能，即使没有运行 Claude 也会如此，因此它受到三重限制：没有密钥时工具拒绝工作，自动更新被关闭，即使开启也会受每小时上限（memory_max_per_hour，默认 10）限制。TG_MEMORY_BASE_URL 可以将调用指向任何兼容的服务（包括本地服务），这样就是免费的。
音频转录（tg_transcribe）——三个引擎，价格不同。Telegram 内置的会在其服务器上计算，并且实际上需要 Premium 才能使用（没有订阅时 Telegram 提供少量免费额度）。Groq 的免费层有请求数量限制，超过后需要付费计划。本地模型完全不花钱：代价是约 1.5 GB 的模型权重和计算时间。
Claude 本身的 token 不在此列——它们由你的客户端计算，而不是 agent。密钥和限额见 docs/configuration.md。
在运行之前阅读，而不是之后。完整内容见 SECURITY.md 和 docs/security.md。
data/session.session 就是无需密码和 2FA 的账户登录凭据。 复制该文件等于账户被盗。它已被 .gitignore 和 .dockerignore 排除，但备份和将目录同步到云端是你的责任。
agent 会给真人发消息。 当 TG_ALLOW_WRITE=1 时，它会以你的名义发送消息，而收件人不会知道不是你发的。
本地索引和档案会把聊天记录写入磁盘，而更新档案会将其发送到外部模型。这两者都不会自动启用：必须明确指定聊天，并且每次此类调用都会记入审计日志。
提示词注入是一个已知问题。在子 agent 的提示词中，他人消息被声明为数据，绝不会被代码解释，但这并不被视为保证：背后有限额、审计和低成本观察者受限的工具集。
聊天中还有另一个人，他并没有同意这些行为。
每小时 60 条消息，每小时最多 15 个不同聊天（反群发），每小时 50 次删除
TG_ALLOW_WRITE=0 完全禁用写入
confirm_writes —— 中间模式：每个写入操作都在 bot 中询问所有者，沉默视为拒绝。只能通过文件修改：agent 不应能够自行解除此限制
每个写入操作都会写入 data/actions.jsonl，并由 tg_actions 读取
收件箱过滤器无法向真人发送消息：操作列表是封闭的
不猜测不明确的聊天名称：工具会返回候选列表
Telegram 的 FloodWait 会以清晰的错误返回，而不是崩溃
uv run tg init # мастер установки, он же «почини установку»
uv run tg doctor # диагностика: что стоит, что сломано, что делать
uv run tg status # что настроено, что нет, состояние демона
uv run tg capabilities # что доступно, что нет и что с этим делать
uv run tg setup # ключи и токен бота
uv run tg login # вход целиком
uv run tg send-code +7XXXXXXXXXX # то же в три шага, без интерактива
uv run tg sign-in --code 12345
uv run tg password # облачный пароль 2FA, только с живого tty
uv run tg link-bot # привязать chat_id для алертов
uv run tg accounts # какие аккаунты залогинены и какой по умолчанию
uv run tg login --account work # добавить второй аккаунт
uv run tg accounts --default work # сменить аккаунт по умолчанию навсегда
uv sync --extra local-whisper # локальная расшифровка звука (опционально)
uv run tg daemon start|run|stop|restart|status|logs
uv run tg call dialogs '{"limit": 5}' # дёрнуть метод демона мимо MCP
uv run tg logout # отозвать сессию и стереть файлы文件 | 说明 |
核心、分层、不变量、数据流、各部分位置 | |
所有 MCP 工具及参数的参考 | |
环境变量、三种写入模式、告警规则、摘要、入站过滤器、多账户、限制 | |
作为 MCP 服务器连接、子代理、诊断 | |
遇到问题时的排查方法： | |
构建、容器内登录、更新、备份 | |
威胁模型：受保护的内容、未受保护的内容、如何撤销访问权限 |
欢迎提交修改——如何搭建环境、PR 前需要运行哪些检查、以及为什么 功能需要同时在三个地方添加，详见 CONTRIBUTING.md。关于漏洞，请参阅 SECURITY.md， 无需创建公开 issue。
MIT, © 2026 Roman Akramov.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Person-owned, portable AI memory as a remote MCP server, readable and writable by any MCP client.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/draiqw/tg-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server