{"id":"70bc01fe-05ea-44a4-bc93-cdfa362e3b24","slug":"tg-parser","kind":"mcp","name":"tg-parser","summary":"Parse Telegram Desktop JSON exports for LLM processing","owner":"mdemyanov","repoUrl":"https://github.com/mdemyanov/tg-parser","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-01-19T19:33:33.000Z","addedAt":"2026-10-21T08:15:59.013Z","logoUrl":"https://avatars.githubusercontent.com/u/2470716?u=bc749eb8e9ea9c70e1fe8d25a885f4e6804dda20&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","utilities"],"tags":["claude","cli","llm","parser","python","telegram"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T21:51:42.233Z","sample":false,"url":"https://conduits.dev/tools/tg-parser","language":"Python","transports":["stdio"],"install":{"pypi":"tg-parser"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# tg-parser\n\n[![PyPI version](https://badge.fury.io/py/tg-parser.svg)](https://pypi.org/project/tg-parser/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/tests-413%20passing-green.svg)](https://github.com/mdemyanov/tg-parser)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Type Checked](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)\n\n**Parse Telegram Desktop JSON exports for LLM processing.**\n\nTransform messy chat exports into clean, structured data ready for summarization, analysis, and artifact extraction with Claude or other LLMs.\n\n## Features\n\n### Implemented ✅ (v1.2.0)\n\n- 🗂️ **All chat types**: Personal, groups, supergroups, forum topics, channels\n- 🔍 **Powerful filtering**: 9 filter types (date, sender, content, topic, attachments, reactions, etc.)\n- ✂️ **Smart chunking**: 3 strategies (fixed, topic, hybrid) for LLM context limits\n- 🚀 **Streaming**: ijson-based reader for files >50MB with auto-detection\n- 📝 **Multiple formats**: Markdown (LLM-optimized), JSON, KB-template, CSV\n- 🔌 **MCP integration**: 6 tools for Claude Desktop/Code\n- 📊 **Statistics**: Message counts, top senders, topics breakdown, mention analysis\n- 🎯 **tiktoken integration**: Accurate token counting (with SimpleTokenCounter fallback)\n- 📄 **split-topics command**: Split forum chats by topic into separate files\n- ✅ **Type-safe**: pyright strict mode, 413 comprehensive tests\n- 🔧 **mcp-config command**: Auto-configure Claude Desktop/Code MCP integration\n- 🆕 **Config file support**: TOML configuration with `config` command group\n\n## Installation\n\n```bash\n# From PyPI (recommended)\npip install tg-parser\n\n# With uv\nuv tool install tg-parser\n\n# With all extras (MCP, tiktoken, streaming)\npip install \"tg-parser[all]\"\n\n# From source\ngit clone https://github.com/mdemyanov/tg-parser.git\ncd tg-parser\nuv sync --all-extras\n```\n\n## Quick Start\n\n### 1. Export from Telegram Desktop\n\n1. Open Telegram Desktop\n2. Go to chat → ⋮ menu → Export chat history\n3. Select JSON format, uncheck media if not needed\n4. Export\n\n### 2. Parse the export\n\n```bash\n# Basic parsing\ntg-parser parse ./ChatExport/result.json -o ./output/\n\n# Last 7 days only\ntg-parser parse ./export.json --last-days 7\n\n# Filter by sender\ntg-parser parse ./export.json --senders \"Иван Петров,Мария\"\n\n# Split forum by topics\ntg-parser parse ./forum_export.json --split-topics\n\n# Chunk for LLM context limits\ntg-parser chunk ./export.json -s hybrid --max-tokens 8000\n\n# Analyze mentions\ntg-parser mentions ./export.json --format json\n\n# Large files with streaming\ntg-parser parse ./massive_export.json --streaming\n\n# Get statistics\ntg-parser stats ./export.json\n```\n\n### 3. Use with Claude\n\nThe output is optimized for LLM processing:\n\n```markdown\n# Chat: Команда разработки\n**Период:** 2025-01-13 — 2025-01-19  \n**Участники:** Иван, Мария, Алексей\n\n---\n\n## 2025-01-15\n\n### 10:30 — Иван Петров\nКоллеги, нужно обсудить архитектуру нового модуля.\n\n### 10:35 — Мария Сидорова\n@Алексей, подготовь диаграмму к завтра.\n```\n\n## CLI Reference\n\n### `tg-parser parse`\n\nMain parsing command with filters.\n\n```bash\ntg-parser parse <input> [OPTIONS]\n\n# Date filters\n--date-from DATE        # Start date (YYYY-MM-DD)\n--date-to DATE          # End date\n--last-days N           # Last N days\n--last-hours N          # Last N hours\n\n# Sender filters\n--senders TEXT          # Include senders (comma-separated)\n--exclude-senders TEXT  # Exclude senders\n\n# Topic filters (for forum groups)\n--topics TEXT           # Include topics\n--exclude-topics TEXT   # Exclude topics\n\n# Content filters\n--mentions TEXT         # Messages mentioning users\n--contains REGEX        # Search pattern\n--min-length N          # Minimum text length\n\n# Type filters\n--has-attachment        # Only with attachments\n--has-reactions         # Only with reactions\n--exclude-forwards      # Exclude forwarded\n--include-service       # Include service messages\n\n# Output\n-o, --output PATH       # Output directory\n-f, --format FORMAT     # markdown|json|csv\n--split-topics          # Separate file per topic\n```\n\n### `tg-parser chunk`\n\nSplit parsed output for LLM context limits.\n\n```bash\ntg-parser chunk <input> [OPTIONS]\n\n-s, --strategy STRATEGY  # fixed|conversation|topic|daily\n--max-tokens N           # Max tokens per chunk (default: 3000)\n--time-gap N             # Minutes gap to split (default: 30)\n--preserve-threads       # Don't break reply chains\n```\n\n### `tg-parser stats`\n\nChat statistics overview.\n\n```bash\ntg-parser stats <input> [OPTIONS]\n\n--format FORMAT          # table|json|markdown\n--top-senders N          # Show top N senders\n--by-topic               # Group by topic\n--by-day                 # Daily breakdown\n```\n\n## MCP Server\n\nUse tg-parser directly in Claude Desktop or Claude Code.\n\n### Setup\n\n```bash\n# Auto-configure (recommended)\ntg-parser mcp-config --apply\n\n# Or manually add to claude_desktop_config.json:\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"tg-parser\": {\n      \"command\": \"uvx\",\n      \"args\": [\"tg-parser\", \"mcp\"]\n    }\n  }\n}\n```\n\n### `tg-parser mcp-config`\n\nGenerate or apply MCP configuration for Claude Desktop/Code.\n\n```bash\ntg-parser mcp-config [OPTIONS]\n\n# Print config to stdout (default)\ntg-parser mcp-config\n\n# Apply to Claude Desktop config\ntg-parser mcp-config --apply\n\n# Dry run - show what would be applied\ntg-parser mcp-config --apply --dry-run\n\n# Apply to Claude Code instead\ntg-parser mcp-config --apply --target code\n\n# Use 'uv run' instead of 'uvx'\ntg-parser mcp-config --use-uv-run\n\nOptions:\n  --apply               Apply config to Claude config file\n  --dry-run             Show what would be written without applying\n  --no-backup           Skip creating backup before modifying\n  --target [desktop|code]  Target application (default: desktop)\n  --use-uv-run          Use 'uv run' instead of 'uvx' for non-venv installs\n  -v, --verbose         Verbose output\n```\n\n### Available Tools\n\n| Tool | Description | Status |\n|------|-------------|--------|\n| `parse_telegram_export` | Parse JSON export with filters | ✅ |\n| `chunk_telegram_export` | Split messages for LLM context | ✅ |\n| `get_chat_statistics` | Get chat statistics (JSON) | ✅ |\n| `list_chat_participants` | List participants with message counts | ✅ |\n| `list_chat_topics` | List forum topics with message counts | ✅ |\n| `list_mentioned_users` | Analyze @mentions frequency | ✅ |\n\n### Example Usage in Claude\n\n```\nUser: Parse my team chat from last week and summarize key decisions\n\nClaude: I'll parse the export and prepare it for analysis.\n[Uses parse_telegram_export tool with date_from filter]\n\nBased on the parsed chat, here are the key decisions...\n```\n\n## Python API\n\n```python\nfrom tg_parser import parse_chat, ChatFilter\nfrom tg_parser.domain.value_objects import FilterSpecification, DateRange\nfrom datetime import datetime, timedelta\n\n# Simple parsing\nchat = parse_chat(\"./export.json\")\nprint(f\"Loaded {len(chat.messages)} messages\")\n\n# With filters\nfilter_spec = FilterSpecification(\n    date_range=DateRange(\n        start=datetime.now() - timedelta(days=7)\n    ),\n    senders=frozenset([\"Иван Петров\"]),\n    exclude_service=True,\n)\nchat = parse_chat(\"./export.json\", filter_spec=filter_spec)\n\n# Access data\nfor topic in chat.topics.values():\n    msgs = chat.messages_by_topic(topic.id)\n    print(f\"{topic.title}: {len(msgs)} messages\")\n\n# Chunking\nfrom tg_parser.application.services.chunker import ConversationChunker\n\nchunker = ConversationChunker(max_tokens=3000)\nchunks = chunker.chunk(chat.messages)\n```\n\n## Output Formats\n\n### Markdown (default)\n\nClean, human-readable format optimized for LLM comprehension.\n\n### JSON\n\nStructured format for programmatic processing:\n\n```json\n{\n  \"meta\": {\n    \"chat_name\": \"Team Chat\",\n    \"chat_type\": \"supergroup_forum\",\n    \"statistics\": {\n      \"total_messages\": 127,\n      \"tokens_estimate\": 15000\n    }\n  },\n  \"messages\": [\n    {\n      \"id\": 1234,\n      \"timestamp\": \"2025-01-15T10:30:00Z\",\n      \"author\": \"Иван Петров\",\n      \"text\": \"...\",\n      \"topic\": \"architecture\"\n    }\n  ]\n}\n```\n\n### CSV\n\nTabular format for spreadsheet analysis.\n\n## Chunking Strategies\n\n| Strategy | Description | Best For |\n|----------|-------------|----------|\n| `conversation` | Split by time gaps + size | General use (recommended) |\n| `fixed` | Fixed token count | Simple cases |\n| `topic` | One chunk per topic | Forum groups |\n| `daily` | One chunk per day | Long time periods |\n\n## Configuration\n\ntg-parser supports TOML configuration files for setting default options.\n\n### Config File Locations (priority order)\n\n1. `--config PATH` CLI flag\n2. `TG_PARSER_CONFIG` environment variable\n3. `./tg-parser.toml` (current directory)\n4. `./.tg-parser.toml` (current directory, hidden)\n5. `~/tg-parser.toml` (home directory)\n6. `~/.tg-parser.toml` (home directory, hidden)\n7. `~/.config/tg-parser/config.toml` (XDG standard)\n\n### Managing Config\n\n```bash\n# Create example config in current directory\ntg-parser config init\n\n# Create in specific location\ntg-parser config init -o ~/.tg-parser.toml\n\n# Show current effective config\ntg-parser config show -v\n\n# Show all search locations\ntg-parser config path\n\n# Use custom config for a command\ntg-parser --config myconfig.toml parse export.json\n```\n\n### Config File Format\n\nCreate `~/.config/tg-parser/config.toml`:\n\n```toml\n[default]\noutput_format = \"markdown\"   # markdown, kb, json, csv\noutput_dir = \"~/Documents/tg-exports\"\n\n[filtering]\nexclude_service = true\nexclude_empty = true\nexclude_forwards = false\nmin_message_length = 0\n\n[chunking]\nstrategy = \"fixed\"           # fixed, topic, hybrid\nmax_tokens = 8000\n\n[output.markdown]\ninclude_extraction_guide = false\nno_frontmatter = false\n\n[mentions]\nmin_count = 1\noutput_format = \"table\"      # table, json\n\n[stats]\ntop_senders = 10\n```\n\n**CLI arguments always override config file values.**\n\n## Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/example/tg-parser\ncd tg-parser\nuv sync --all-extras\n\n# Run tests\nuv run pytest\n\n# Type check\nuv run pyright\n\n# Lint and format\nuv run ruff check --fix\nuv run ruff format\n\n# Run CLI in dev mode\nuv run tg-parser parse ./test.json\n```\n\n## Architecture\n\nClean Architecture with clear separation:\n\n```\npresentation/  →  application/  →  domain/  ←  infrastructure/\n   (CLI, MCP)     (use cases)    (entities)    (adapters)\n```\n\n## Documentation\n\n- **[CLAUDE.md](CLAUDE.md)** — AI assistant system prompt and development methodology\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — Clean Architecture layers, domain model, design decisions\n- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — Development guide, common tasks, testing guidelines\n- **[docs/TELEGRAM_FORMAT.md](docs/TELEGRAM_FORMAT.md)** — Telegram JSON export format specification\n- **[PRD.md](PRD.md)** — Product requirements, roadmap, implementation status\n- **[CHANGELOG.md](CHANGELOG.md)** — Version history and release notes\n\n## Development Status\n\n**Current Version:** 1.2.0 (Stable)\n\n| Component | Status | Details |\n|-----------|--------|---------|\n| Core parsing | ✅ Complete | All chat types, topics, reactions |\n| Filtering | ✅ Complete | 9 filter types |\n| Chunking | ✅ Complete | 3 strategies (fixed, topic, hybrid) |\n| Streaming | ✅ Complete | ijson reader, auto-detection >50MB |\n| CLI | ✅ Complete | 7 commands: `parse`, `stats`, `chunk`, `mentions`, `split-topics`, `mcp-config`, `config` |\n| MCP Server | ✅ Complete | 6 tools for Claude integration |\n| Writers | ✅ Complete | Markdown, JSON, KB-template, CSV |\n| Config | ✅ Complete | TOML config files, `config` command group |\n| Tests | ✅ Complete | 413 tests, pyright strict |\n| PyPI | ✅ Published | v1.2.0 available |\n| CI/CD | ✅ Automated | GitHub Actions for testing & releases |\n\n### Roadmap\n\n- **v1.0.0**: ✅ **RELEASED** - Production stable, PyPI published, CI/CD automated\n- **v1.1.0**: ✅ **RELEASED** - CSV output, split-topics command, tiktoken integration\n- **v1.2.0**: ✅ **RELEASED** - TOML config file support, `config` command group\n\nSee [PRD.md](PRD.md) for detailed roadmap.\n\n## Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing`)\n3. Make changes with tests\n4. Ensure `uv run pytest` and `uv run pyright` pass\n5. Submit PR\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [Telegram Desktop](https://desktop.telegram.org/) for export functionality\n- [Typer](https://typer.tiangolo.com/) for CLI framework\n- [MCP](https://modelcontextprotocol.io/) for Claude integration"}