Atlas / MCP servers / kfastov / Tgcli

TgcliCAUTION

Name: Tgcli
Author: kfastov

mcp/kfastov/tgcli

MCP server by kfastov · agent skill · ai · ai agents · Audited 2026-10-08

⚑ Report / re-scan Source ↗

Telegram user console client and archiver

Verdict

CAUTION

Grade

Trust score

89 /100

Exposed tools

38 37r · 1w · 0d

Transport

streamable-http

License

MIT

Stars

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Telegram CLI with background sync and an optional MCP server for your personal account (MTProto, not bot API).

Installation

npm install -g @kfastov/tgcli

brew install kfastov/tap/tgcli

Authentication

Get Telegram API credentials:

Go to https://my.telegram.org/apps
Log in with your phone number
Create a new application
Copy api_id and api_hash

Then authenticate:

tgcli auth

Quick start

tgcli auth
tgcli sync --follow
tgcli messages list --chat @username --limit 20
tgcli messages search "course" --chat @channel --source archive
tgcli send text --to @username --message "hello"
tgcli server

Commands

tgcli auth           Authentication and session setup
tgcli config         View and edit config
tgcli sync           Archive backfill and realtime sync
tgcli server         Run background sync service (MCP optional)
tgcli service        Install/start/stop/status/logs for background service
tgcli channels       List/search channels
tgcli messages       List/search messages
tgcli send           Send text or files
tgcli media          Download media
tgcli topics         Forum topics
tgcli tags           Channel tags
tgcli metadata       Channel metadata cache
tgcli contacts       Contacts and people
tgcli groups         Group management
tgcli doctor         Diagnostics and sanity checks

Use tgcli [command] --help for details. Add --json for machine-readable output.

MCP (optional)

Enable it via config:

tgcli config set mcp.enabled true

By default the server binds to http://127.0.0.1:8080/mcp. To change it:

tgcli config set mcp.host 127.0.0.1
tgcli config set mcp.port 8080

Then run tgcli server and point your client at the configured address.

Configuration & Store

The tgcli store lives in the OS app-data directory and contains config.json, sessions, and messages.db. Override the location with TGCLI_STORE.

Legacy version: s

Read from source at commit 3cc5b904b81aOBSERVED · 2026-10-08

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.

claude-code

claude mcp add tgcli -- npx -y @kfastov/[email protected]

claude-desktop

{
  "mcpServers": {
    "tgcli": {
      "command": "npx",
      "args": [
        "-y",
        "@kfastov/[email protected]"
      ]
    }
  }
}

Exposed tools (38)

37 read · 1 write · 0 destructive.

Tool	Risk	Description
`autoTagChannels`	read	Auto-tags channels based on title, username, and cached metadata.
`contactsAliasRemove`	read	Removes alias for a contact.
`contactsAliasSet`	read	Sets an alias for a contact.
`contactsGet`	read	Returns a contact profile from the local store.
`contactsNotesSet`	read	Sets notes for a contact.
`contactsSearch`	read	Searches contacts/users with aliases, tags, and notes.
`contactsTagsAdd`	read	Adds tags to a contact.
`contactsTagsRemove`	read	Removes tags from a contact.
`getChannelMetadata`	read	Returns cached metadata for a channel.
`getSyncedMessageStats`	read	Returns summary statistics for stored messages in a channel.
`groupsInfo`	read	Fetches group information and metadata.
`groupsInviteLinkGet`	read	Gets the primary invite link for a group.
`groupsInviteLinkRevoke`	read	Revokes the primary invite link for a group.
`groupsJoin`	read	Joins a group using an invite link or code.
`groupsLeave`	read	Leaves a group chat or channel.
`groupsList`	read	Lists group chats and supergroups.
`groupsMembersAdd`	read	Adds members to a group.
`groupsMembersRemove`	read	Removes members from a group.
`groupsRename`	read	Renames a group chat or supergroup.
`listActiveChannels`	read	Lists dialogs tracked in the local archive registry.
`listChannelTags`	read	List tags attached to a channel.
`listChannels`	read	Lists available Telegram dialogs for the authenticated account, including unread message counts.
`listMessageSyncJobs`	write	Lists tracked message sync jobs and their current status.
`listTaggedChannels`	read	List channels that carry a specific tag.
`markChannelRead`	read	Marks a Telegram channel as read up to the specified message ID.
`mediaDownload`	read	Downloads media from a message to a local file.
`messagesContext`	read	Returns surrounding messages for a target message.
`messagesGet`	read	Fetches a specific message from the archive or live Telegram API.
`messagesList`	read	Lists messages from the archive or live Telegram API.
`messagesSearch`	read	Searches messages across the archive or live Telegram API.
`messagesSend`	read	Sends a text message to a channel or chat.
`messagesSendFile`	read	Sends a file with an optional caption.
`refreshChannelMetadata`	read	Fetches and caches extended metadata for channels.
`scheduleMessageSync`	read	Schedules a background job to archive channel messages locally.
`searchChannels`	read	Searches dialogs by title or username.
`setChannelTags`	read	Assign tags to a channel for later cross-channel search.
`topicsList`	read	Lists forum topics for a supergroup.
`topicsSearch`	read	Searches forum topics by title.

Trust audit

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

Layer	What it checks	Result
L0	Provenance & inventory	PASS
L1	Static analysis of the code	WARN
L2	Instruction surface (what it tells the agent)	PASS
L3	Class-specific surface	WARN
L4	Behavioural (sandbox)	SKIPPED

What the source does

Filesystem: declared (2 observation(s))
Network: declared (4 observation(s))
Shell: declared (1 observation(s))
Dependencies: not all pinned
Secrets in source: none-found

Findings (9)

MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319

core/control-client.js:75

return `http://127.0.0.1:${control.port}${pathname}`;

MEDIUMNetwork egress · net.raw_ip · CWE-200, CWE-319

core/control-server.js:89

url = new URL(req.url ?? '', 'http://127.0.0.1');

MEDIUMAuth / authz · mcp.remote_no_auth · CWE-287, CWE-862

streamable-http

Why it matters. a network transport with no auth environment variable found

Fix. require a token

LOWFilesystem / path · fs.traversal · CWE-22, CWE-59

tests/folders.test.js:550

await expect(tc.joinChatlist('https://t.me/addlist/abc/../../evil')).rejects.toThrow('Invalid chatlist link');

LOWNetwork egress · net.raw_ip · CWE-200, CWE-319

README.md:70

By default the server binds to `http://127.0.0.1:8080/mcp`. To change it:

LOWNetwork egress · net.raw_ip · CWE-200, CWE-319

tests/control-client.test.js:81

expect(url).toBe('http://127.0.0.1:8765/control/ping');

LOWNetwork egress · net.raw_ip · CWE-200, CWE-319

tests/control-client.test.js:108

expect(url).toBe('http://127.0.0.1:8765/control/backfill');

LOWSupply chain · supply.unpinned · CWE-829, CWE-1357

package.json

@modelcontextprotocol/sdk, @mtcute/core, @mtcute/node, better-sqlite3, commander, qrcode, vitest

Why it matters. 7 dependency range(s) float

Fix. pin exact versions or ship a lockfile

LOWPrompt injection · prompt.transfer_instruction · CWE-94, CWE-1427

AGENTS.md:26

- Add coverage when extending `telegram-client.js` or `message-sync-service.js` by mocking MTProto responses to validate session reuse and message archiving.

Why it matters. an instruction to move sensitive data to an outside destination

Fix. remove; a skill never needs the user's secrets off the machine

Gates applied: no_behavioural_pass.

Audited 2026-10-08 · audit v0.4.1 · source sha 3cc5b904b81afull audit observations/trust-audit/mcp-server/kfastov__tgcli.json · Report an issue / request a re-scan

Audit history

Every audit this server has had. A grade with a past is a grade somebody is still checking.

Date	Source	Verdict	Grade	Score	Change
2026-10-08	`3cc5b904b81a`	CAUTION	B	89	first audit

Questions

What is the Tgcli MCP server?

Telegram user console client and archiver

What tools does Tgcli expose?

38 in total: 37 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.

Is Tgcli safe to connect to an agent?

With care. The audit graded it B (89/100) and found 9 things worth knowing before you trust this server, listed below with the exact line each was found on.

What credentials does Tgcli need?

No credential environment variables were found in its source, so it appears to need none.

How does Tgcli run?

It speaks streamable-http, so it runs as a service you connect to over the network. It is published on npm as @kfastov/tgcli at 2.2.3.

How current is this page?

The grade is for one exact copy of the source (3cc5b904b81a), read on 2026-10-08. The repository is watched and re-audited when it changes.

Source	kfastov/tgcli
npm	`@kfastov/tgcli@2.2.3`
Transports	streamable-http
License	MIT
Activity	pushed 17d ago