Skip to main content
Glama
serjteplov

tg-mcp-spy

by serjteplov
OverviewSchemaRelated ServersScoreDiscussions
Python

tg-mcp-spy

A Python MCP (Model Context Protocol) server that caches Telegram channel posts in a local SQLite database and exposes them via MCP tools. It connects to Telegram through a user session (Telethon) and mirrors the user's broadcast-channel subscriptions into a queryable local cache.

Quick start

1. Install dependencies

uv sync --all-extras

2. Set environment variables

export TELEGRAM_API_ID=your_api_id
export TELEGRAM_API_HASH=your_api_hash
export TELEGRAM_SESSION_STRING=your_session_string

The session string must be generated externally (e.g. via Telethon's interactive login). Optional variables:

Variable

Default

Description

TGMCPSPY_DB_PATH

tgmcpspy.db

Path to the SQLite database

TGMCPSPY_POST_TTL_DAYS

90

Days to retain cached posts

3. Run the server

python -m package_tgmcpspy.server

The server binds to 127.0.0.1:8000 by default.

Related MCP server: tg-mcp-tools

MCP Tools

Tool

Description

list_tracked_channels

List all locally tracked channels

add_channel(channel)

Add a channel to the local tracked list

remove_channel(channel)

Remove a channel from the local tracked list

sync_dialogs

Sync tracked channels with your Telegram subscriptions

update_channel(channel)

Fetch latest posts for a single channel

update_all_channels

Fetch latest posts for all tracked channels

get_post(channel, post_id)

Get a specific cached post

list_channel_posts(channel, start_date, end_date)

List posts from one channel by date range

list_all_posts(start_date, end_date)

List posts from all tracked channels by date range

Channel identifiers accept a Telegram username or numeric id (including -100... format). Dates accept YYYY-MM-DD or ISO timestamps, interpreted as UTC.

MCP Resources

URI

Description

channel://list

Tracked channels (placeholder; use the tool for live data)

post://{channel}/{post_id}

Single cached post (placeholder; use the tool for live data)

MCP Prompt

URI

Description

channel_digest://{channel}

Summarize recent posts from a channel (default: last 7 days)

Development

make format    # Format code with ruff
make lint      # Run ruff linter
make typecheck # Run mypy
make test      # Run pytest
make check     # Run format-check + lint + typecheck + test

Architecture

src/package_tgmcpspy/
  models.py      — domain dataclasses, exceptions, identifier normalization
  config.py      — environment-based configuration loading
  db.py          — SQLAlchemy Core schema + async repository
  telegram.py    — Telethon wrapper with FloodWait retry
  server.py      — FastMCP application, lifespan, tools, resources, prompts

All MCP tool calls are processed sequentially. Cached posts are immutable — edits and deletions on Telegram are ignored. Posts older than the configured TTL are purged automatically.

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/serjteplov/tg-mcp-spy'

If you have feedback or need assistance with the MCP directory API, please join our Discord server