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:

2026 Trend	Industry State	KommoMCP Status
Planner-Executor separation	Emerging standard (Lu et al. 2025, Rosario et al. 2025). LangGraph, CrewAI, AutoGen adopt this pattern	✅ Implemented: deterministic graph planner + LLM executor
MCP Protocol	Anthropic's MCP becoming the HTTP of agents (broad adoption 2025-2026)	✅ Full MCP support: stdio + HTTP transport
Graph-based tool planning	NeurIPS 2024: "Can Graph Learning Improve Planning in LLM-based Agents?" — graph planners outperform flat RAG	✅ Tool Graph with 54 nodes, 24 edges, backward chaining, topo sort
Plan-and-Execute cost pattern	Frontier model plans, cheaper models execute — 90% cost reduction (MLMastery 2026)	✅ Planner is zero-cost (no LLM), executor sees only 2-6 tools
Deterministic guardrails	"Bounded autonomy" — deterministic control flow with LLM flexibility (Deloitte 2026)	✅ Fixed chain order, param refs, dependency enforcement
Multi-agent orchestration	1,445% surge in multi-agent inquiries Q1'24→Q2'25 (Gartner)	⚡ Sequential pipeline with parallel step detection
Tool scoping / least privilege	Best practice: filter tools per step, not expose all (Stack AI 2026)	✅ LLM sees only planned tools, not all 54
Observability / audit trail	"Treat agent like distributed system" — traces, costs, handoffs	✅ Interaction logger, session logs, admin panel
Human-in-the-Loop	Strategic HITL for high-stakes decisions (MLMastery 2026)	✅ Confirm dialogs for destructive ops (delete, reset)
FinOps for agents	Cost-performance as first-class concern	✅ Chain cost metric, planner adds 0ms to latency

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

Command	Description
/start	Start, show welcome
/connect	Connect new CRM
/crm_list	List all connected CRMs
/switch	Switch active CRM
/status	Current CRM status
/openai	Set OpenAI API key
/sync	Sync CRM data to local DB
/wizard	CRM setup wizard
/remove_crm	Disconnect a CRM
/help	All commands
/cancel	Cancel current operation

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