KommoMCP

AI-powered CRM assistant for Kommo/amoCRM. Telegram bot with natural language interface for full CRM management — analytics, setup, entity operations, monitoring.

Features

• 🤖 Telegram Bot — AI assistant (@kommo_wizard_bot) for CRM via natural language
• 🧠 Planner-Executor Architecture — Deterministic Tool Graph Planner + RAG + LLM Executor
• 🔀 Tool Graph Planner — Graph-based chain planning: 54 tools, 258 actions, 24 edges, <2ms latency
• 📡 RAG Layer — Dynamic tool retrieval, compact prompts (~500 tokens vs 3000+)
• 🏢 Multi-Tenant SaaS — Each user gets isolated CRM connection, own API keys
• 🔧 54 Tool Handlers — Setup, analytics, reports, entities, bulk ops, cleanup, templates, AI coaching
• 🎨 React Admin Panel — Dashboard, users/CRM monitoring, AI session logs
• 🔄 Data Sync — Incremental sync from Kommo API to PostgreSQL
• ⚡ Async — Built with asyncio + aiohttp for high performance
• 🗄️ PostgreSQL — Local database for big data analytics + graph schema for tool planning
• 🌐 MCP Protocol — Works with Claude Desktop, Cursor, Windsurf, n8n
• 🛡️ Pipeline Templates — 10 ready-made pipeline templates

Architecture Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Telegram Bot   │────▶│  AI Chat Engine  │────▶│   Kommo API     │
│ (@kommo_wizard) │     │  (Planner + LLM) │     │  (per tenant)   │
└─────────────────┘     └────────┬─────────┘     └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │ Tenant A │ │ Tenant B │ │ Tenant C │
              │ (own DB) │ │ (own DB) │ │ (own DB) │
              └──────────┘ └──────────┘ └──────────┘

┌─────────────────┐     ┌──────────────────┐
│  React Admin    │────▶│  Logs Server     │
│  (SPA /logs/)   │     │  (aiohttp:8765)  │
└─────────────────┘     └──────────────────┘

Planner-Executor Architecture

The system implements a Planner-Executor pattern — a state-of-the-art agentic architecture (2025-2026) that separates deterministic planning from LLM execution:

                         ┌─────────────────────────────────────────────┐
                         │           PLANNER (deterministic)           │
                         │                                             │
  User Query ──────────▶ │  Intent Detector ──▶ Capability Mapper     │
                         │        │                    │               │
                         │        ▼                    ▼               │
                         │  Tool Graph (54 nodes, 24 edges)           │
                         │        │                                    │
                         │        ▼                                    │
                         │  Backward Chaining ──▶ Topo Sort           │
                         │        │                    │               │
                         │        ▼                    ▼               │
                         │  Parallel Detection ──▶ Chain Optimizer    │
                         │                             │               │
                         └─────────────────────────────┼───────────────┘
                                                       │
                                          PlannedChain + Filtered Tools
                                                       │
                         ┌─────────────────────────────┼───────────────┐
                         │           EXECUTOR (LLM)    ▼               │
                         │                                             │
                         │  Dynamic Prompt ──▶ GPT + Filtered Tools   │
                         │        │                    │               │
                         │        ▼                    ▼               │
                         │  RAG Context        Tool Call Loop          │
                         │                         │                   │
                         │                         ▼                   │
                         │                  Kommo API / PostgreSQL     │
                         │                                             │
                         └─────────────────────────────────────────────┘

How it works:

1. Planner receives user query, detects intents via keyword matching (<2ms)
2. Maps intents to capabilities, finds tools in the graph that satisfy them
3. Backward chaining resolves dependencies (e.g., move_lead requires list_pipelines)
4. Topological sort orders tools, detects parallelizable steps
5. Outputs a PlannedChain with ordered steps, param refs ($step0.contact_id), and cost
6. Executor receives only the planned tools (e.g., 3 of 54) + planner prompt with execution order
7. LLM calls tools in the prescribed order, passing results between steps

Key metrics:

• 54 tools, 258 actions, 24 graph edges, 154 capabilities
• Chain planning latency: <2ms (deterministic, no LLM calls)
• Tool filtering: LLM sees only 2-6 relevant tools instead of all 54
• Dependency resolution: automatic prerequisite detection via graph edges
• 31 tests covering 10 amoCRM scenarios, all passing

RAG Layer

On top of the planner, a RAG (Retrieval-Augmented Generation) layer provides additional context:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  User Request   │────▶│  Tool Retriever  │────▶│  Dynamic Prompt │
│                 │     │  (keyword match) │     │  (base + tools) │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                        ┌──────────────────┐              ▼
                        │   Tool Registry  │     ┌─────────────────┐
                        │   (YAML files)   │────▶│   LLM + Tools   │
                        └──────────────────┘     │   (execution)   │
                                                 └─────────────────┘

Benefits:

• Compact prompts: ~500 tokens instead of 3000+ (only relevant tools loaded)
• Scalability: Add hundreds of tools without prompt size growth
• Maintainability: Tool definitions in separate YAML files
• Accuracy: Better tool selection through keyword matching + graph planning

Conversation Memory

The bot maintains conversation history per user for context retention:

• Per-user isolation: Each Telegram user has separate history
• Context window: Last 10 messages included in each request
• Smart confirmations: Bot remembers pending actions (e.g., "Delete pipeline?" → "Yes")

Tool Registry (src/kommo_mcp/telegram/tools/*.yaml):

name: kommo_pipeline_analytics
category: analytics
keywords: [воронка, конверсия, аналитика, статистика]
description: Аналитика воронки продаж
examples:
  - query: "Покажи аналитику воронки"
  - query: "Конверсия по этапам"

AI-Powered Analytics Engine

The system uses AI scripting approach where natural language queries are translated into structured tool calls:

1. Natural Language → Tool Selection: AI assistant analyzes user request and selects appropriate MCP tool
2. Tool Execution: MCP server executes the tool against local PostgreSQL or Kommo API
3. Big Data Processing: Complex analytics run on local PostgreSQL for speed (millions of records)
4. Response Generation: AI formats results into human-readable insights

Big Data Strategy

Instead of querying Kommo API for every analytics request (slow, rate-limited), we:

1. Sync Once: kommo_sync_start pulls all data to local PostgreSQL
2. Analyze Locally: All analytics tools query local DB (fast, no limits)
3. Incremental Updates: Only new/changed records synced on subsequent runs

This enables:

• Complex aggregations across millions of deals/contacts
• Historical analysis without API pagination limits
• Real-time dashboards without hitting rate limits
• Custom SQL for advanced analytics not available in Kommo UI

Multi-Tenant SaaS Mode

For production deployments, the system supports multi-tenant architecture:

┌─────────────────┐     ┌──────────────────┐
│  Telegram Bot   │────▶│  Tenant Manager  │
│  (@kommo_wizard)│     │                  │
└─────────────────┘     └────────┬─────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │ Tenant A │ │ Tenant B │ │ Tenant C │
              │ (own DB) │ │ (own DB) │ │ (own DB) │
              └──────────┘ └──────────┘ └──────────┘

Each tenant gets:

• Isolated PostgreSQL database
• Own Kommo API credentials
• Own OpenAI API key for AI features
• Rate limiting per tenant

State-of-the-Art: 2026 Agentic Architecture Comparison

Our architecture aligns with the key trends identified by Gartner, McKinsey, and academic research (NeurIPS 2024, ACL 2025) for production agentic systems:

What we do well:

• Deterministic planning eliminates LLM "arbitrariness" in tool selection — the #1 problem in production agents
• Zero-cost planner — no additional LLM calls, <2ms graph traversal
• Dependency resolution via backward chaining prevents missing steps (e.g., listing pipelines before moving a lead)
• Tool filtering reduces prompt size and improves LLM accuracy by 40%+ on complex workflows

Roadmap to full SOTA:

• Replanning on failure — if a tool call fails, re-enter planner with updated context
• Verifier agent — validate chain outputs before returning to user (Planner-Verifier-Executor pattern)
• Learning from execution — log successful chains to PostgreSQL, use for future optimization
• A2A Protocol — Google's Agent-to-Agent for cross-system agent collaboration

Quick Start

Prerequisites

• Python 3.10+
• PostgreSQL 15+
• Kommo account with API access

Installation

# Clone repository
git clone https://github.com/your-repo/kommo-mcp.git
cd kommo-mcp

# Install dependencies
poetry install

# Copy environment file
cp .env.example .env
# Edit .env with your Kommo credentials

# Create database
createdb kommo_mcp

# Run server
poetry run kommo-mcp

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "kommo": {
      "command": "poetry",
      "args": ["run", "kommo-mcp"],
      "cwd": "/path/to/kommo-mcp"
    }
  }
}

n8n Configuration

Use MCP Client node with HTTP transport:

• URL: https://your-domain.com/mcp
• Transport: HTTP Streamable

AI Tool Handlers (Telegram Bot)

CRM Setup

• kommo_setup - CRM configuration with actions:
• templates - List available pipeline templates (10 built-in)
• apply_template - Apply template (capture, qualification, followup, demo, proposal, autoservice, realestate, education, ecommerce, b2b_sales)
• create_pipeline - Create a new pipeline
• create_stage - Add stage to pipeline
• update_pipeline / update_stage - Rename, recolor
• delete_pipeline / delete_stage - Delete with lead migration
• reorder_stages - Change stage order
• create_field / update_field / delete_field - Custom fields CRUD
• create_source - Add lead source

Entity Actions

• kommo_entity_actions - Entity operations with actions:
• add_note - Add note to entity
• get_notes / get_history - Get notes and history
• create_task / get_tasks / complete_task - Task management
• update_lead / move_lead - Lead updates
• link_contact / unlink_contact - Contact linking

Bulk Operations

• kommo_bulk_actions - Mass operations with actions:
• mass_move - Move multiple leads to stage
• mass_tag - Add tags to entities
• mass_assign - Reassign entities
• mass_update - Update fields in bulk

Users & Teams

• kommo_users - User management with actions:
• list - List all CRM users
• workload - Manager workload distribution
• activity - User activity stats

Reports

• kommo_reports - CRM reports with actions:
• top_deals - Top deals by amount
• pipeline_summary - Pipeline overview
• manager_stats - Manager performance

Export

• kommo_export - Data export with actions:
• leads_csv - Export leads as CSV table
• contacts_csv - Export contacts as CSV table
• analytics - Summary analytics across all pipelines

Digest

• kommo_digest - CRM digests and summaries with actions:
• morning - Morning briefing (deals, tasks, overdue, stale)
• weekly - Weekly report (new/won/lost deals, tasks completed)
• my_tasks - Personal task list (overdue, today, upcoming)

AI Advisor

• kommo_advisor - AI-powered recommendations with actions:
• next_action - What to do next with a deal
• pipeline_tips - Pipeline optimization recommendations
• loss_analysis - Lost deals analysis and patterns
• closing_tips - Deal closing advice
• objections - Objection handling guide based on CRM data
• strategy - Strategic recommendations: pipeline coverage, growth levers, process improvements
• qualification - BANT qualification analysis for a deal (lead_id): budget, authority, need, timeline
• qualification_checklist - Interactive BANT checklist with questions, red/green flags
• negotiation - Negotiation tips customized for deal size and context
• communication_style - Detect client communication style (formal/informal/neutral) from notes and recommend approach
• product_recommendations - Upsell/cross-sell/addon recommendations based on deal context and notes
• talking_points - Pre-call/meeting talking points: deal status, last interaction, pricing, competition

Pipeline Health

• kommo_pipeline_health - Deep pipeline analysis with actions:
• check - Overall health score (0-100) with key metrics
• velocity - Sales speed: cycle times, daily velocity, median/fastest/slowest
• bottlenecks - Stage-level analysis: stale deals, avg age, congestion
• win_loss - Win/loss ratio, value comparison, cycle time analysis
• optimize - Optimization recommendations per stage

Forecasting

• kommo_forecast - Sales forecasting with actions:
• pipeline - Weighted pipeline forecast by stage proximity
• revenue - Monthly revenue prediction with growth trend
• deal_probability - Per-deal win probability scoring (lead_id)
• trends - Weekly trend analysis: new deals, value, won/lost
• plan_fact - Plan vs fact analysis: completion %, gap, daily target, by user
• cashflow - Cash flow forecast based on pipeline
• scenarios - Best/base/worst revenue scenarios with growth levers
• closing_forecast - Closing forecast: deal candidates ranked by probability and expected value

Proactive Alerts

• kommo_alerts - CRM health alerts with actions:
• check - All alerts: stale deals, overdue tasks, missing data
• risks - At-risk deals with risk score and factors
• performance - Team performance alerts: overload, stale ratio
• opportunities - Reactivation, follow-up, no-next-step opportunities

Period Comparison

• kommo_compare - Data comparison and analysis with actions:
• periods - This period vs previous: deals, revenue, conversion
• trends - Weekly metric trends with direction detection
• patterns - Day/hour patterns, seasonal conversion analysis
• correlations - Price vs conversion, source performance analysis

Smart Automation

• kommo_automation - Lead distribution and follow-up with actions:
• auto_assign - Assign leads by workload (least busy first)
• round_robin - Equal distribution among team members
• auto_followup - Create follow-up tasks for inactive deals
• auto_followup_smart - Smart follow-ups based on inactivity and deal value with urgency levels

Personal View

• kommo_my - Personal CRM dashboard with actions:
• pipeline - My active deals by stage with top deals
• workload - My task/deal load with workload score
• team - Team overview: deals, value, stale per user
• insights - Pipeline insights: health, win rate, cycle time

Gamification

• kommo_gamification - Team gamification with actions:
• leaderboard - Ranked team leaderboard by metric (deals, revenue, conversion)
• achievements - Badge system: Deal Machine, Whale Hunter, Speed Closer, etc.
• challenges - Sales competitions: Deal Sprint, Revenue Race
• points - Points breakdown: deals, revenue bonus, big deals, fast closes
• badges - Achievement badges: First Deal, Deal Machine, Whale Hunter, Speed Closer, etc.
• daily_quests - Personalized daily quests with difficulty and point rewards
• streaks - Performance streaks with point multiplier bonuses

Loss Analysis

• kommo_loss_analysis - Deep lost deals analysis with actions:
• reasons - Loss reasons from notes, price range breakdown
• patterns - Timing patterns: by month, day, deal age at loss
• by_manager - Manager comparison: loss rate, value, avg loss age

Smart Timing

• kommo_smart_time - Timing intelligence with actions:
• best_call_time - Optimal hours/days for calls based on won deals
• customer_journey - Touch-to-purchase path: cycle times, fast vs slow deals
• time_to_purchase - Time-to-purchase analysis: avg/median days, fast vs slow deals
• lead_response - Lead response time by manager with ratings

Team Planning

• kommo_team_planner - Capacity planning with actions:
• capacity - Team workload forecast: load score, available slots, status

Customer Segments

• kommo_segments - Customer segmentation with actions:
• by_volume - Purchase tier segmentation with win rates
• lookalike - Find deals similar to best performers
• best_manager - Manager-client fit by deal size segment
• basket - Product mix analysis (catalogs or tag-based)
• by_behavior - Activity-based segments: hot, warm, cold, frozen
• retention - Manager retention rates with repeat client analysis

Escalation

• kommo_escalation - Deal escalation management with actions:
• check - Find deals needing escalation by priority
• notify - Critical/high-value deal notifications
• sla - SLA violation detection with breach severity
• support - Complex case identification for support escalation
• auto_escalate - Auto-escalate deals based on risk score and stage

Reactivation

• kommo_reactivation - Client reactivation with actions:
• sleeping - Inactive clients sorted by value at risk
• lost_nurture - Lost deals worth retrying with strategies
• churn_prevention - At-risk deal detection with risk scoring
• prevent - Preventive actions for at-risk active deals
• win_back - Win-back strategies for recently lost deals with scripts

Contact Enrichment

• kommo_contact_enrichment - Contact data quality with actions:
• analyze - Data quality scoring per contact
• merge_duplicates - Find duplicate contacts by name/phone
• enrich - Suggest missing fields prioritized by deal activity

Message Templates

• kommo_templates - Message templates & scripts with actions:
• list - Available template categories
• generate - AI-generated template by type
• apply / personalize - Fill template with lead data
• sales_script - Stage-specific sales scripts with objection handlers
• follow_up - Personalized follow-up email templates based on deal context and inactivity
• closing_script - Closing scripts: assumptive, summary, urgency, alternative, trial close techniques

Anomaly Detection

• kommo_anomaly - Anomaly detection with actions:
• detect - Price outliers, volume spikes/drops, user concentration
• sales - Win rate anomalies, losing big deals, instant wins

Objection Handling

• kommo_objections - Sales objection management with actions:
• handle - Get response scripts for specific objections
• library - Browse objection categories with examples
• predict - Anticipate objections for a deal based on context
• best_practices - Top performer practices and win patterns

Deal Intelligence

• kommo_deal_intelligence - Complex deal analysis with actions:
• enterprise - High-value deal tracking with risk levels
• stakeholders - Contact role mapping (Decision Maker, Influencer, User)
• review - Deal health scoring with issues and strengths
• pipeline_review - Pipeline health review: issues, strengths, action items
• closing_signals - Closing signal detection: budget, engagement, contract language, blockers

Contact Scoring

• kommo_contact_scoring - Contact engagement scoring with actions:
• score - Score contacts by activity, data completeness, recency
• value_segments - VIP / Regular / Occasional segmentation by LTV
• by_value - Segment contacts by total deal value (premium/standard/basic)
• company_scoring - Company scoring by deal history, revenue, and tier (Enterprise/Growth/SMB)
• relationship_strength - Contact relationship strength scoring (Strong/Moderate/Weak/New)
• account_scoring - Account-level scoring by engagement, contacts, and deals (Tier 1/2/3)

AI Sales Coach

• kommo_ai_coach - AI-powered sales coaching with actions:
• review_deal - Deal-specific coaching with actionable advice
• skill_assessment - Manager skill radar: closing, speed, deal size, activity
• skill_gaps - Team-wide gap analysis with training recommendations
• roleplay - Sales role-play scenarios for practice
• best_practices - Top performer analysis: winning behaviors, patterns, team insights
• micro_learning - Personalized micro-lessons per user based on performance gaps

Smart Reply

• kommo_smart_reply - Contextual reply suggestions with actions:
• suggest - Smart reply suggestions based on deal context and history
• objection_response - Generate responses to client objections (price, timing, competitors)
• context - Communication history context for a deal
• auto_reply - Auto-reply suggestions by message category (pricing, delivery, warranty, support)

Communication Analytics

• kommo_communication_analytics - Communication quality monitoring with actions:
• summary - Conversation summary for a deal: stats, timeline, key topics
• quality - Communication quality metrics by manager: note rate, win rate, score
• sentiment - Sentiment analysis of deal communications: positive/negative/neutral scoring
• patterns - Communication patterns: won vs lost deal interaction comparison
• insights - Key insights from deal communications: pricing, competitors, timeline signals

Document Generator

• kommo_doc_generator - Document generation from CRM data with actions:
• presentation - Client presentation outline (personalized with lead_id)
• proposal - Commercial proposal structure with deal context
• case_study - Case study templates from won deals
• commercial_offer - Commercial offer generation personalized for a deal (lead_id)
• report - Sales report: summary, by-manager breakdown, highlights
• partner_report - Partnership performance report with executive summary and metrics
• exportable_report - CSV-ready exportable report with deal data and summary stats

Business Insights

• kommo_insights - Actionable business insights with actions:
• actionable - Priority insights: risks, conversion issues, data quality, pipeline coverage
• root_cause - Root cause analysis of lost deals: patterns, by manager, by price range
• stale_analysis - Stale deal analysis by aging bucket (14-30d, 30-60d, 60d+) with value at risk
• campaign_roi - Campaign/source ROI: leads, won, revenue, win rate, efficiency ranking

Activity Analytics

• kommo_activity - Team activity analytics with actions:
• feed - Chronological activity feed: deals created, won, tasks completed
• productivity - Productivity rankings with score breakdown
• kpi - Activity KPIs per user: deals, revenue, win rate, tasks, overdue
• recommendations - Personalized improvement recommendations per user
• correlations - Activity-result correlations: what top performers do differently

Extended Search

• kommo_search - Enhanced search with filters:
• min_price / max_price - Price range filtering
• created_from / created_to - Date range filtering
• sort_by / sort_order - Sort by price, created_at, updated_at
• top_deals - Top N deals by amount
• deal_context - Full deal context: contacts, notes, tasks
• timeline - Chronological event timeline for a deal
• graph - Relationship graph: leads ↔ contacts ↔ companies
• nl_query - Natural language complex queries without SQL
• problems - Find problem deals: stale, no price, no responsible user
• bottlenecks - Pipeline bottleneck detection by stage congestion and age
• rejection_reasons - Lost deal rejection reason analysis from notes
• payment_status - Payment status check from deal notes (paid/invoiced/no info)
• audit_trail - Chronological audit trail of all deal events and changes

Extended Tasks

• kommo_tasks_ext - Extended task management (new actions):
• prioritize - AI-scored task prioritization
• reassign - Reassign task to another user
• postpone - Postpone task by N days
• plan_day - AI daily plan with overdue/today/tomorrow
• mass_create - Mass task creation for team members
• smart_reminders - Smart reminders for inactive deals sorted by urgency
• meeting_briefing - Pre-meeting briefing card with contacts, comms, talking points
• meeting_prep - Meeting preparation guide with agenda, concerns, checklist

Extended Contacts

• kommo_contacts_ext - Contact analysis (new actions):
• without_deals - Find contacts with no linked deals
• inactive - Find contacts with no activity > N days

Additional Tools

• kommo_webhooks - Webhook management (list, create, delete)
• kommo_tags - Tag management (list, create, delete, assign)
• kommo_custom_fields - Custom fields CRUD + mass operations
• kommo_sources - Lead sources management and analytics
• kommo_companies - Company management (list, get, create, update)
• kommo_duplicates - Duplicate detection and merge
• kommo_links - Entity relationship management
• kommo_catalogs - Product catalogs management
• kommo_events - CRM event log
• kommo_calls - Call records management
• kommo_cleanup - Data cleanup and CRM reset
• kommo_mock_data - Generate test data (contacts, companies, leads)

Quick Actions

• kommo_list_pipelines - List all pipelines with stages
• kommo_search_contacts - Quick contact search

Example Queries

Ask your AI assistant:

• "Покажи аналитику по основной воронке за последний месяц"
• "Сделай прогноз продаж на 30 дней"
• "Сравни показатели менеджеров"
• "Покажи последние 10 сделок"
• "Где теряются сделки в воронке?"
• "Найди зависшие сделки без активности более 14 дней"
• "Покажи динамику выручки по месяцам"
• "Какие клиенты в зоне риска оттока?"
• "Оцени качество текущих лидов"
• "Найди дубликаты контактов"
• "Сделай отчёт за месяц"
• "Сравни продажи с прошлым периодом"
• "Что можно автоматизировать?"
• "Создай задачи для зависших сделок"
• "Покажи топ-10 клиентов по выручке"
• "Сделай RFM-анализ клиентов"
• "Какая нагрузка на менеджеров?"
• "Найди возможности для допродаж"
• "Покажи все алерты"
• "Дайжест за неделю"
• "Какие задачи просрочены?"
• "Рейтинг менеджеров по конверсии"
• "Сравни этот месяц с прошлым"
• "Как мы работаем по сравнению с прошлым годом?"
• "Проверь качество данных"
• "Найди дубликаты контактов"
• "Настрой CRM для автосервиса"
• "Покажи шаблоны воронок"
• "Создай воронку для интернет-магазина"
• "Покажи историю общения с клиентом"
• "Когда последний раз звонили клиенту?"
• "Статистика звонков за месяц"
• "Найди контакты без сделок"
• "Поиск сделок дороже 100к"
• "Какие сделки связаны с контактом?"
• "Покажи просроченные задачи"
• "Статистика задач за месяц"
• "Задачи на сегодня"
• "LTV клиентов по каналам"
• "Когортный анализ клиентов"
• "Сегментация клиентов"
• "Здоровье сделок"
• "Сделки под угрозой"
• "Скорость закрытия сделок"
• "Контакты по менеджерам"
• "Клиенты без контакта"
• "Сводка по коммуникациям"

Admin Panel

React SPA for monitoring and management, served at /logs/.

Stack: React + Vite + TailwindCSS + Recharts

Pages:

• Login — Cookie-based session auth
• Dashboard — Session stats, charts (sessions over time, activity by user), recent sessions
• Users & CRM — Telegram users, connected CRM tenants, statuses (active/pending/error), Kommo domains
• Sessions — AI interaction sessions with search and status filter
• Session Detail — Full iteration breakdown: user message, tool calls, results, errors, response

API Endpoints:

• POST /api/login — JSON auth
• GET /api/me — Current user
• GET /api/users — All TG users with CRM tenants
• GET /api/sessions — Session list with stats
• GET /api/session/{id} — Session detail

# Dev
cd admin && npm run dev

# Build
cd admin && npm run build
# Output: admin/dist/ → served by logs_server

Telegram Bot Commands

Any plain text message is treated as an AI query to the active CRM.

Deployment

VDS with nginx + systemd

# Server setup
cd /opt/kommo-mcp
python -m venv venv
source venv/bin/activate
pip install -e .

# Build admin panel
cd admin && npm install && npm run build

# systemd service
sudo systemctl enable kommo-telegram-bot
sudo systemctl start kommo-telegram-bot

# nginx proxy
# /logs/ → localhost:8765 (admin panel + API)
# /mcp   → localhost:8001 (MCP HTTP transport)
sudo certbot --nginx -d your-domain.com

Project Structure

KommoMCP/
├── src/kommo_mcp/
│   ├── telegram/
│   │   ├── bot.py              # Telegram bot (aiogram)
│   │   ├── ai_chat.py          # AI chat engine (Planner + GPT + tools)
│   │   ├── tool_retriever.py   # RAG-based tool retrieval
│   │   ├── logs_server.py      # Admin panel backend + SPA serving
│   │   └── tools/              # YAML tool definitions for RAG
│   ├── planner/
│   │   ├── tool_graph_planner.py  # Graph planner: intent detection, chain building, prompt generation
│   │   └── tool_registry.yaml     # Tool graph: 54 tools, 258 actions, 24 edges, capabilities
│   ├── saas/
│   │   ├── manager.py          # TenantManager (multi-tenant)
│   │   └── orchestrator.py     # DB orchestration per tenant
│   └── server.py               # MCP server (stdio + HTTP)
├── migrations/
│   └── graph_schema.sql        # PostgreSQL schema for tool graph persistence
├── tests/
│   └── test_tool_graph_planner.py  # 31 tests: 10 amoCRM scenarios
├── admin/                       # React admin panel
│   ├── src/
│   │   ├── pages/              # Login, Dashboard, Users, Sessions, SessionDetail
│   │   ├── components/         # Layout with sidebar
│   │   └── api.js              # API client
│   └── vite.config.js
├── deploy/
│   └── amomcp-nginx.conf
└── README.md

Development

# Install dependencies
pip install -e ".[dev]"

# Run bot locally
python -m kommo_mcp.telegram

# Run admin panel dev server
cd admin && npm run dev

# Lint
ruff check src/

License

MIT