Telegram Lead Analysis MCP

A read-only MCP server that exposes a team's Telegram lead conversations to Claude for sales analysis — lead summary, intent, stage, objections, next/missed follow-ups, hot/warm/cold, action items.

The server does no reasoning and calls no LLM. It returns clean, structured message data; the connected Claude client does the thinking.

Status

• Data source today: a Telegram Desktop JSON export (frozen snapshot).
• Data source later: a live Telethon connection (same interface, no tool changes). The TelethonLeadDataSource stub is already in place.

Guarantees

• Read-only by construction. There is no send/edit/delete code path anywhere.
• Whitelist enforced at the data layer (datasource/base.py), not just in the tools — a tool physically cannot return a non-whitelisted chat.
• Every tool call is logged with the chat it touched to logs/access.log.
• No credentials in code. The live source reads TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_SESSION from the environment only.

Project layout

server.py                 MCP server + tool definitions
datasource/
  base.py                 LeadDataSource interface (whitelist + text normalize)
  json_source.py          JSONLeadDataSource (active)
  telethon_source.py      TelethonLeadDataSource (stub for live access)
config/whitelist.json     JSON list of in-scope lead chat names
data/leads_export.json    the export (sample fixture ships; replace with real)
logs/access.log           access log (created at runtime)
requirements.txt

Go live with Edrian's account (copy-paste runbook)

You have his api_id, api_hash, and session string. Do this once:

1. Paste the 3 values into .env (open the .env file in the project root):

TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=abc123...
TELEGRAM_SESSION=1Aa...

2. List his chats so you can pick the leads:

.\.venv\Scripts\python.exe list_all_chats.py

3. Put the lead chat names into config/whitelist.json (exactly as printed), e.g.:

["Acme Corp", "Beta Logistics"]

4. Test it end-to-end against the live account:

.\.venv\Scripts\python.exe -c "import server; print(server.list_chats())"

That's it — the server auto-detects the credentials and uses the live account (LEADS_SOURCE=auto). To go back to the sample export for testing, set LEADS_SOURCE=json in .env. The session string lives only in .env (which is gitignored) — never in code.

Setup

Requires Python 3.10+.

# from the project root
python -m venv .venv
# Windows PowerShell:  .venv\Scripts\Activate.ps1
# macOS/Linux:         source .venv/bin/activate
pip install -r requirements.txt

1. Provide the data

Replace data/leads_export.json with the slimmed lead-chat export (lead chats only — not a full account dump). The loader accepts the standard Telegram Desktop shapes: {"chats": {"list": [...]}}, a top-level list, or a single-chat {"name", "messages"} object.

A sample fixture ships in the repo so you can run the server immediately.

2. Set the whitelist

Edit config/whitelist.json — a JSON array of the exact chat names that are leads. Anything not listed is invisible to every tool.

["Acme Corp — Jordan", "Beta Logistics — Priya"]

Tip: run list_chats after pointing the loader at the full export to see the names, then narrow the whitelist to the real leads.

Tools

Tool	Status	What it does
list_chats	✅	Whitelisted chats: name, message count, last message date.
get_chat_messages(chat_name, limit=100, since_date=None)	✅	Cleaned message history for one whitelisted chat.
analyze_lead_conversation(chat_name)	✅	Full thread as ordered {sender, timestamp, text} for the client to analyze.
search_chats	🚧 stub	Keyword search across whitelisted chats.
extract_followups	🚧 stub	Promised/missed follow-ups.
summarize_conversation	🚧 stub	Server-side summary (deferred).
create_task_or_note	🚧 stub	Task/note creation (write path, inert).

Run / smoke test

# Verify the data layer and tools without an MCP client:
python smoke_test.py

To run the MCP server directly (it speaks stdio and waits for a client):

python server.py

Deploy to Railway (remote URL connector)

For connecting Claude to a hosted URL instead of running locally. The server auto-switches to HTTP transport when a PORT env var is present (Railway sets it), so no code change is needed.

1. Push this repo to GitHub (done) and create a Railway project from the repo.

2. Set environment variables in Railway (Settings → Variables) — these replace the local .env, which is never committed:

Variable	Value
TELEGRAM_API_ID	Edrian's api_id
TELEGRAM_API_HASH	Edrian's api_hash
TELEGRAM_SESSION	the session string
LEADS_WHITELIST_JSON	(optional) inline JSON array of lead chat names; overrides the committed config/whitelist.json so client names need not live in git
TELEGRAM_FETCH_LIMIT	(optional) default 500

Railway provides PORT automatically — don't set it.

3. Deploy. Railway builds via Nixpacks (requirements.txt) and runs python server.py (see Procfile / railway.json). The MCP endpoint is:

https://<your-app>.up.railway.app/mcp

4. Connect Claude (claude.ai → Settings → Connectors → Add custom connector) to that /mcp URL.

⚠️ Security: this endpoint exposes the account's lead chats to anyone who can reach the URL — it has no built-in auth. Keep the URL private, and prefer putting an auth layer (or Railway private networking) in front of it before sharing. The session string is full account access; treat the deployment as sensitive.

Register with Claude Desktop

Add this to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Use absolute paths.

{
  "mcpServers": {
    "telegram-lead-analysis": {
      "command": "d:\\ZeroPenny\\Telegram MCP\\.venv\\Scripts\\python.exe",
      "args": ["d:\\ZeroPenny\\Telegram MCP\\server.py"]
    }
  }
}

Restart Claude Desktop, then ask it to "list my Telegram lead chats" or "analyze the Acme Corp lead".

Switching to live Telegram (later)

1. Implement the _raw_* hooks in datasource/telethon_source.py.
2. In server.py, swap the one line in build_data_source() from JSONLeadDataSource(...) to TelethonLeadDataSource(whitelist).
3. Set TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_SESSION in the environment (e.g. via the Claude Desktop config "env" block). No tool definitions change.

A note on the export Edrian sent

The export received was the entire account (672 chats, contacts, stories, phone number) — far more than the lead chats and a privacy over-share. Treat it as a throwaway test fixture only. For the real build we need just the specific lead chats plus the session credentials. Tell Edrian he over-shared.