Skip to content
Back to search

mcpgram

Self-hosted Telegram Corporate MCP Server with dynamic Telegram RBAC

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mytischi--mcpgram/badge.svg)](/listings/mytischi--mcpgram)

HTML

<a href="/listings/mytischi--mcpgram"><img src="/api/listings/mytischi--mcpgram/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: Docker Compose (`lite` profile, prebuilt multi-arch GHCR image)

curl -O https://raw.githubusercontent.com/mytischi/mcpgram/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/mytischi/mcpgram/main/.env.example
cp .env.example .env
# Edit BOT_TOKEN (from @BotFather with Privacy Mode disabled) and ADMIN_TG_IDS
docker compose --profile lite pull
docker compose --profile lite up -d

Option B: Run locally from source (Go)

cp .env.example .env
# Set DATABASE_URL=./data/mcpgram.db for local macOS/Linux runs
go build -o bin/mcpgram ./cmd/mcpgram
./bin/mcpgram serve

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 89 lines
  1. # mcpgram
  2. Self-hosted Telegram Corporate MCP Server written in Go.
  3. Allows employees to safely connect their AI agents (Cursor, Claude Desktop, OpenCode, CLI agents, etc.) to corporate Telegram group chats via **MCP (Model Context Protocol)** over Streamable HTTP — with strict Read-Only access and dynamic RBAC synchronized with Telegram chat membership.
  4. ## Key Principles
  5. - **Privacy by default:** all messages stay inside your infrastructure (local SQLite WAL + FTS5 in `lite` mode); no access to personal DMs.
  6. - **Telegram as Source of Truth (RBAC):** users can query only the chats where they are active members (hybrid `chat_member` push + TTL-bounded live `getChatMember` verification, fail-closed on network errors).
  7. - **Read-Only MCP:** no send/write/delete tools exposed to LLMs; bearer tokens live in the MCP client config, never in LLM prompts.
  8. - **Long Polling only:** no public IP, domain, or inbound webhooks required; optional HTTP/SOCKS5 `TELEGRAM_PROXY_URL`.
  9. - **Configurable history & retention policies:** `DEFAULT_HISTORY_POLICY=full_history` (or `since_join`, plus per-chat `/set_policy`), `RETENTION_DAYS=0` (keep forever by default), and `TOKEN_TTL_DAYS=90` (`0` for non-expiring tokens until revoked).
  10. ## Quick Start
  11. ### Option A: Docker Compose (`lite` profile, prebuilt multi-arch GHCR image)
  12. ```bash
  13. curl -O https://raw.githubusercontent.com/mytischi/mcpgram/main/docker-compose.yml
  14. curl -O https://raw.githubusercontent.com/mytischi/mcpgram/main/.env.example
  15. cp .env.example .env
  16. # Edit BOT_TOKEN (from @BotFather with Privacy Mode disabled) and ADMIN_TG_IDS
  17. docker compose --profile lite pull
  18. docker compose --profile lite up -d
  19. ```
  20. ### Option B: Run locally from source (Go)
  21. ```bash
  22. cp .env.example .env
  23. # Set DATABASE_URL=./data/mcpgram.db for local macOS/Linux runs
  24. go build -o bin/mcpgram ./cmd/mcpgram
  25. ./bin/mcpgram serve
  26. ```
  27. ## Bot Setup & Connecting MCP Clients
  28. 1. In `@BotFather`, create a bot, run `/setjoingroups` → **Enable** and `/setprivacy` → **Disable**.
  29. 2. Add the bot to your corporate Telegram groups as **administrator** (strip dangerous rights like delete/ban/pin).
  30. 3. Send `/auth` to the bot in a private DM to obtain your personal Bearer token (`tgmcp_...`).
  31. 4. Add `mcpgram` to your MCP client config (`mcp.json` / `claude_desktop_config.json`):
  32. ```json
  33. {
  34. "mcpServers": {
  35. "company-telegram": {
  36. "url": "http://localhost:8080/mcp",
  37. "headers": {
  38. "Authorization": "Bearer tgmcp_your_token_here"
  39. }
  40. }
  41. }
  42. }
  43. ```
  44. ## Bot Commands (Private DM)
  45. | Command | Who | Description |
  46. |---|---|---|
  47. | `/start` | Anyone | Shows your numeric `Telegram ID` and available commands |
  48. | `/auth` | Corporate chat members & admins | Issues a personal Bearer token (revokes any previous token) |
  49. | `/status` | `ADMIN_TG_IDS` | Shows bot diagnostics, Privacy Mode status, and tracked chats (`ws=...`) |
  50. | `/set_policy <ws_id> <full_history\|since_join\|default>` | `ADMIN_TG_IDS` | Sets or resets per-chat history visibility override |
  51. | `/revoke_user <telegram_user_id>` | `ADMIN_TG_IDS` | Immediately revokes all active tokens for a user |
  52. ## Import Historical Archive (Telegram Desktop JSON)
  53. Export chat history to JSON in Telegram Desktop (`result.json`) and run:
  54. ```bash
  55. ./bin/mcpgram import --file /path/to/result.json
  56. # Optional: override Bot API chat ID or limit age with --retention-days:
  57. ./bin/mcpgram import --file /path/to/result.json --chat-id -1001234567890 --retention-days 0
  58. ```
  59. ## MCP Tools (Read-Only)
  60. - `list_chats` — accessible corporate chats, Forum Topics, and last message timestamp.
  61. - `search_messages` — RBAC-filtered FTS5 search across accessible chats or a specific chat/topic.
  62. - `get_messages` — chronological messages filtered by date range, topic, and author.
  63. - `get_thread` — full reply chain reconstruction around a `message_id`.
  64. ## Development & Tests
  65. ```bash
  66. go vet ./...
  67. go test -race ./...
  68. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.