프로필별 쓰기 제한 기능을 통해 AI 클라이언트가 사용자의 Telegram 계정에서 메시지를 읽고, 검색하고, 검토하고, 전송할 수 있게 합니다.
다른 이름 WireCatLabs/tg-cli, tg-cli, @wirecat/tg-cli
- 스타
- 16
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.130.0
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
Telegram MCP란?
Telegram은(는) MCP server입니다. 프로필별 쓰기 제한 기능을 통해 AI 클라이언트가 사용자의 Telegram 계정에서 메시지를 읽고, 검색하고, 검토하고, 전송할 수 있게 합니다.
프로젝트 README에서 생성된 요약
Telegram MCP server 정보
WireCat Telegram은 AI 에이전트를 통해 Telegram 통신을 관리할 수 있게 해줍니다. 이 도구를 사용하면 Claude Desktop, Cursor, Claude Code와 같은 AI 클라이언트가 단순한 봇이 아닌 사용자의 실제 Telegram 계정과 상호작용할 수 있습니다. 로컬 우선 인터페이스로 작동하여 메시지를 읽고, 검색하고, 전송할 수 있으며, 개인적인 검색을 위해 채팅 기록을 컴퓨터에 로컬로 저장합니다.
사용자는 직접 Telegram 앱을 등록하고 QR 코드 또는 전화번호를 통해 로그인하여 연결을 설정합니다. 이 서버는 여러 프로필을 지원하므로 서로 다른 계정이나 컨텍스트를 분리할 수 있습니다. 의도치 않은 동작을 방지하기 위해 프로필별 쓰기 제한 기능이 포함되어 있으며, 기본적으로 시간당 30개의 메시지 제한이 적용됩니다. 개발자는 tg personal mcp serve 명령어를 사용하여 로컬 MCP server에 연결할 수 있으며, 메시지 확인이나 그룹 채팅 내 미답변 질문 검토와 같은 작업을 위한 즉시 사용 가능한 프롬프트를 제공받을 수 있습니다.
활용 사례
- 1최근 약속 요약AI 에이전트에게 최근 채팅에서 약속한 내용을 확인하도록 요청하여 할 일을 관리할 수 있습니다.
- 2특정 정보 찾기전체 메시지 기록을 검색하여 회의 장소나 계약 조건과 같은 특정 세부 정보를 찾을 수 있습니다.
- 3그룹 활동 모니터링특정 그룹 내의 답변되지 않은 질문을 식별하여 토론이 활발하게 유지되도록 합니다.
- 4메시지 답장 자동화AI 클라이언트를 사용하여 연락처에 대한 답장이나 리마인더 초안을 작성하고 전송할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Telegram MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Telegram MCP 설치
$ claude mcp add tg-cli -- npx -y @wirecat/tg-cliCursor에 Telegram MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"tg-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/tg-cli"
]
}
}
}VS Code에 Telegram MCP 설치
.vscode/mcp.json
{
"servers": {
"tg-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@wirecat/tg-cli"
]
}
}
}VS Code CLI에 Telegram MCP 설치
$ code --add-mcp '{"name":"tg-cli","type":"stdio","command":"npx","args":["-y","@wirecat/tg-cli"]}'Claude Desktop에 Telegram MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"tg-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/tg-cli"
]
}
}
}Codex에 Telegram MCP 설치
$ codex mcp add tg-cli -- npx -y @wirecat/tg-cliCodex config.toml에 Telegram MCP 설치
~/.codex/config.toml
[mcp_servers.tg-cli] command = "npx" args = ["-y", "@wirecat/tg-cli"]
Gemini CLI에 Telegram MCP 설치
$ gemini mcp add -s user tg-cli npx -- -y @wirecat/tg-cliGemini settings.json에 Telegram MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"tg-cli": {
"command": "npx",
"args": [
"-y",
"@wirecat/tg-cli"
]
}
}
}구성
TG_PROFILE
| 이름 | 설명 | 유형 |
|---|---|---|
| TG_PROFILE | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기tg — Telegram CLI for AI agents
An example conversation (invented people, illustrative output):
You: Use tg CLI. What did I promise anyone in the last three days?
Agent: (runs tg personal review 'date>3d': 12 chats)
I owe
· Alice Example — the invoice by Friday. "Alice Example", 24.09
Waiting on others
· Bob Sample — the mock-up by 25.09. Not in "Design" yet
You: Remind Bob about the mock-up.
Agent: Draft: "Hi Bob, how is the mock-up going?" Send it?
You: Yes.
Quick start
npm install -g @wirecat/tg-cli # or: bun add -g @wirecat/tg-cli; pnpm: see docs/installation.md
tg skill install --for all # the agent skill, for Claude Code, Codex and Gemini CLI
tg personal setup # app registration and login
tg personal inbox # other people's unread messages, in every chat; nothing is marked read
A global install does not install the agent skill: tg personal setup offers it, or run tg skill install --for all. npm may warn that install scripts are blocked or "not yet covered by allowScripts" (@wirecat/tg-cli,
better-sqlite3); that is harmless, and you need not allow them — why.
On Windows, if tg is not found, open a new terminal, or use the PowerShell installer in
the installation guide.
Allow about five minutes. tg personal setup registers your own Telegram app at
my.telegram.org, logs in by QR code, checks your first chats and installs
the agent skill. Downloading older history is a separate step.
It needs Node 22.19+ or 24+, or Bun, on macOS, Linux or Windows. Try it without installing:
npx @wirecat/tg-cli --help.
More: installation guide · on wirecat.dev
What can you do?
Catch up. "Use tg CLI. What came in since this morning, and who is waiting for my answer?"
tg personal inbox
tg personal review 'date>1d'
Find anything. "Use tg CLI. When did we agree on the venue with Alice?" — an answer with the date and the message itself.
tg personal search all "venue" # messages and notes on this computer, and Telegram's own search
By default the words also go to Telegram's server search; add --offline to keep the query on this computer.
Keep your promises. "Use tg CLI. What did I promise, and what am I still waiting on?" tg personal review
hands over everything said since the last review in one call, your own messages too.
tg personal review --new # what changed since the last review --new
Run your groups. "Use tg CLI. Which questions in Hiking has nobody answered?"
tg personal review chat:Hiking --unanswered
tg personal chats events "Hiking" "time>=7d" # who joined, left, was added or removed
More: recipes, with a schedule and limits for each · on wirecat.dev
Built for AI agents
Your agent. Your Telegram. Your rules.
- Agents with a terminal (for example Claude Code, Codex, Gemini CLI) run
tgcommands themselves. The bundled skill tells them how:tg personal setup --agent …ortg skill installputs it in place, andtg skill showprints it before login. - Apps without a terminal (for example Claude Desktop, Cursor and other MCP clients) connect to
tg personal mcp serve. It comes with ready prompts:/catch-up,/review,/reply,/find,/open-tasksand/link-conversations.
tg personal mcp add claude-code # or: tg personal mcp add codex
tg personal mcp config # the entry for Claude Desktop, Cursor and others
The profile can send by default, so mcp add stops first. Check the profile's permissions, then run
it again with --allow-writes.
More: the MCP server · on wirecat.dev
Why tg?
- Your whole account, not only bots. Every chat, group, channel and contact, with its history —
tgis one more of your devices. - Local-first search. Everything read is kept on your computer. Search reads that copy and, by default,
asks Telegram's own search too;
--offlinekeeps the query on your computer. - Made for agents. One operation per call, the same JSON shape every time with
--json, a fixed exit code for each kind of failure, an MCP server and a skill. - Safe by default. Reading marks nothing read. A profile decides which actions an agent may take,
which chats it may send to, and how many messages an hour (30 by default). When a send's outcome is
unknown,
tgsays so and gives a repeat command that Telegram does not deliver twice. - The full Bot API too. All 185 methods, next to the convenient bot commands.
More: compared with other tools · on wirecat.dev
Your account
tg works in your name, as one more of your devices. It is not a bot: it talks to Telegram over
MTProto, Telegram's own API for client apps, with an app you register yourself. It sees your chats,
their history, groups, channels and contacts.
tg personal chats list --limit 5
tg personal messages list "Book club" --limit 20
tg personal messages send "Book club" "Call at 3?" --reply-to <id>
tg personal reactions add "Book club" <id> 👍
tg personal messages send me "Call mum" --at-time 2h # a reminder in Saved Messages in two hours
tg personal messages send "Book club" "The minutes" --file minutes.pdf
tg personal messages download "Book club" <id> --output-dir ~/Downloads
tg personal messages transcribe "Book club" <id> # a voice message as text
- Read. Chats, history, one message with its neighbours, other people's unread messages in every
chat (
tg personal inbox), everything since the last review (tg personal review), new messages as they arrive (tg personal watch), a message's files, voice messages as text. - Write. Markdown, replies, files, photos, videos and voice messages, silent and scheduled messages (they go out even with this computer off), edits, forwards, pins, reactions, polls, deletion — for you or for everyone.
- Voice on your computer. Telegram transcribes for Premium accounts;
tgcan also run a speech model on this machine, downloaded only when you ask. - Contacts and the account. Add, rename, block and import contacts; your own aliases and notes for people; who you are logged in as, and every device logged in to the account.
- One person. Their profile, when they were last seen, their messages per shared chat, and whether the account looks like a bot or a spammer.
More: using tg · on wirecat.dev · one person · on wirecat.dev
Log in and profiles
Every user registers their own Telegram app; tg personal setup or tg personal session start does it for you. The
app keys go to the system keyring, and the session is a file only your user can read.
tg personal session start # a QR code: Settings → Devices → Link Desktop Device
tg personal session start phone # or a phone number, the code and your 2FA password
tg personal session start qr # without a terminal (an agent): the QR code as text to paste into the chat
tg personal account show # who you are logged in as
tg account list # every profile here, and who each is logged in as
Several accounts are several profiles, and the profile is the first word, not an option:
tg personal chats list # profile "personal"
tg work chats list # profile "work"
export TG_PROFILE=work # or for the whole shell session
tg never picks a profile for you, not even the only one: a command that uses an account and has no
profile named stops and lists the profiles on this computer. Name one, or set TG_PROFILE for a
whole shell session.
More: login and sessions · on wirecat.dev · profiles · on wirecat.dev
The local store and search
Everything tg reads is kept in a local store on your computer. Search runs over it and over
Telegram by default; --offline answers from the store without connecting.
tg personal search messages 'contract chat:"Project Alpha"'
tg personal search messages "contract" --backend archive # local only
tg personal messages sync "Project Alpha" --last 5000 --background
tg personal store export "Project Alpha" --format markdown --output alpha.md
tg personal messages evidence "Project Alpha" --json # bounded evidence for a chat brief
tg personal server install # keep the store current as a systemd or launchd service
tg personal store backup ~/tg-backup.db # a copy, safe while the store is in use
Search by words, people, dates, files, links and tags; save searches; find discussions by topic.
More: search · on wirecat.dev · the local store · on wirecat.dev
Groups you run
tg personal review chat:Hiking --unanswered # questions nobody answered in 24 hours
tg personal chats events "Hiking" "time>=7d" # who joined, left, was added or removed, and by whom
tg personal chats members list "Hiking" --all # everyone, with their role and when they were last seen
tg personal topics list "Hiking" # a forum group's topics, newest activity first
tg personal chats inspect https://t.me/+AbCdEf # where an invite link leads, without joining
tg personal chats create "Hiking 2027" @alice_example # a new group, with the people you name
tg personal stats chats show "Hiking" # group activity
Renaming a group, adding and removing members and admins, join requests, invite links, forum topics and moderation rules for links, forwards and floods are commands too.
More: groups you run · on wirecat.dev
A bot
tg personal bot works with a bot through Telegram's official Bot API and
its token from @BotFather. You can keep several bots; each has a name you
choose, and that name is the first word of the command.
tg sales bot auth set # the token, at a hidden prompt; Telegram checks it first
tg sales bot auth show # which bot it is
tg sales bot recipients add user:<id> # the bot may write only here
tg sales bot messages send "Team" "Build is ready" --file report.pdf
tg sales bot api --help # every Bot API method, each with its fields
tg personal bot list --check # every bot on this computer
- Every Bot API method.
tg <bot> bot api <method>takes native field flags or a JSON body. - One token per name, in the keyring, apart from your own login;
TG_BOT_TOKENfor CI. The token is never printed — not in an error, not with--trace, not in a run record. - Recipients and a journal. Each bot has its own list of chats it may write to, and a journal of what it did, without the text.
- Messages, admins, members, buttons, the menu, webhooks — send, edit, delete and pin;
bot chats admins,bot callbacks answer,bot commands,bot webhooks. - History.
bot watchprints and keeps what happens in the bot's chats;bot messages syncimports older channel and supergroup messages.
More: a Telegram bot · on wirecat.dev
Agent setup in detail
The skill. Claude Code reads ~/.claude/skills/tg-cli/; Codex, Gemini CLI and local Cursor read
~/.agents/skills/tg-cli/. Start a new agent session if it does not see the skill.
tg skill install --for all # both folders, without logging in
tg skill show # the complete instructions, without installing them
The MCP server. Commands stay discoverable with their arguments and current availability. The
profile's permissions decide which may run. readonly stops writes; at ask the server shows no
form, so set up approval in your agent app.
claude mcp add tg -- tg personal mcp serve # Claude Code, by hand
claude mcp add tg -- tg mcp serve --profiles all # one server for every profile
tg personal mcp check # check the local MCP server
From the browser. ChatGPT or Claude in the browser reach tg personal mcp serve --http --public-url <url> behind
your tunnel, after a login with a one-time access code from your terminal.
More: the MCP server · on wirecat.dev · remote access · on wirecat.dev
Output for scripts and agents
With --json a command prints only data, as one JSON value — no tables, colour or hints; it does the
same when another program reads its output. --jsonl prints one object per line. Every list has one
shape:
{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }
An error goes to stderr as one line, with stdout empty, and the command exits with a fixed code: 4
log in, 5 the profile may not do this, 6 chat or message not found, 8 a limit, 9 Telegram did
not answer in time, 14 unknown whether a message went. tg commands --json is the whole command
tree. A partial read or download can exit 0: check complete in the JSON.
More: CLI contract · on wirecat.dev · every command and exit code · on wirecat.dev
Settings and permissions
tg personal config set permissions.messages readonly # no change to messages from this profile
tg personal config set permissions.messages.send ask # a question in the terminal before each send
tg personal config set sends_per_hour 10 # at most 10 sends an hour (30 by default)
tg personal recipients add "Book club" # the first add turns the recipient list on
tg personal sends list # every attempt: sent, refused, failed or not known
tg personal config show # what is set, and where it came from
More: permissions · on wirecat.dev · configuration · on wirecat.dev
Limits
Each profile has one request pace, shared by every command, background job and server at once, so bulk work stays under Telegram's limits. Short waits from Telegram are waited out; a long wait stops the run instead of being repeated.
More: limits and waits · on wirecat.dev
Security
- The session file is as good as your password, readable only by your user; the app keys are in the system keyring. No command takes a password, a login code or a phone number as an argument.
- The local store holds the full text of what was read, unencrypted and readable only by your user. It stays after logout; only whole-disk encryption protects it from a stolen disk.
- Every send, from a command or over MCP, passes the profile's limits and is written to a journal —
without its text.
--filerefuses credential files, CLI folders and the local store. - Control characters in names, titles and messages are shown as text, so other people's text cannot control your terminal.
- The limits stop an agent talked into sending by a message it read, not one that sets out to get round them: for that, run the agent in a sandbox or as a separate user.
To report a vulnerability: SECURITY.md.
More: security · on wirecat.dev
When something goes wrong
tg personal doctor # where the files are and whether a session is saved, without connecting
tg personal doctor --online # check that the login works
tg personal chats list --trace # each request to Telegram, with no text, names, phone numbers or keys
tg personal runs list # recorded runs
More: troubleshooting by symptom · on wirecat.dev · diagnostics · on wirecat.dev
How it differs
Telegram's own apps are made for a person; tg is made for a script and an agent. A Telegram bot sees
only the chats it was added to and speaks as the bot; tg is you, in your chats. Other open tools
connect a Telegram account to an agent too: tgcli, telegram-mcp and tdl.
More: compared with other tools · on wirecat.dev
Part of WireCat
WireCat is an open-source, local-first context layer for AI agents. tg is
where it starts; max-cli brings the MAX messenger into the
same local store. Start with Telegram. Add more context when you need it. Your context. Any agent.
Questions and setup help: join the WireCat Discord. Bugs go to this repository's issues.
Telegram MCP 질문
Telegram MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add tg-cli -- npx -y @wirecat/tg-cli를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Telegram MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
봇이 아닌 제 개인 Telegram 계정으로 작동하나요?
네, 직접 등록한 Telegram 앱을 통해 MTProto를 사용하여 사용자의 기기 중 하나로 로그인하므로 모든 채팅과 기록을 볼 수 있습니다.
MCP 클라이언트가 이 서버를 통해 Telegram에 어떻게 연결하나요?
MCP server 명령어를 실행한 후 생성된 설정 항목을 Claude Desktop, Cursor 또는 다른 MCP 클라이언트에 추가하면 됩니다.
에이전트가 메시지를 보낼 수 있나요? 제한이 있나요?
메시지 전송은 가능하지만 제한이 있습니다. 프로필별로 전송 가능한 채팅방과 시간당 메시지 수를 설정할 수 있으며, 기본값은 시간당 30개입니다.
메시지를 검색하면 쿼리가 Telegram으로 전송되나요?
기본적으로 로컬 복사본과 Telegram 서버 검색을 모두 수행합니다. 쿼리를 컴퓨터 내에서만 유지하려면 --offline 옵션을 사용하세요.
메시지를 읽으면 읽음 처리되나요?
아니요, 메시지를 읽어도 읽음 상태로 변경되지 않으며 inbox 명령어를 사용해도 아무것도 읽음 처리되지 않습니다.