amocrm-mcp 0.1.0__tar.gz

amocrm_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+build/
+*.egg-info/
+.eggs/

amocrm_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amocrm_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: amocrm-mcp
+Version: 0.1.0
+Summary: MCP server for AmoCRM — gives Claude Desktop direct access to your CRM
+Project-URL: Homepage, https://github.com/ilyaberdysh/amocrm-mcp
+Project-URL: Issues, https://github.com/ilyaberdysh/amocrm-mcp/issues
+License: MIT
+License-File: LICENSE
+Keywords: amocrm,claude,crm,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# AmoCRM MCP Server
+
+MCP-сервер для [AmoCRM](https://www.amocrm.ru/). Подключается к Claude Desktop и даёт Claude прямой доступ к вашей CRM через 17 инструментов.
+
+Задавайте вопросы на русском — Claude сам вызовет нужные API и скомбинирует ответ.
+
+## Архитектура
+
+```
+┌──────────────────┐     stdin/stdout      ┌──────────────────┐     HTTPS      ┌──────────────┐
+│  Claude Desktop  │ ◄──── MCP Protocol ──► │  amocrm-mcp      │ ◄── REST ───► │  AmoCRM API  │
+│  (LLM + UI)      │                        │  (локальный)      │                │  (облако)    │
+└──────────────────┘                        └──────────────────┘                └──────────────┘
+```
+
+**Как это работает:**
+
+1. Claude Desktop запускает `amocrm-mcp` как subprocess
+2. MCP-сервер сообщает Claude: "у меня 17 инструментов — get_leads, get_contacts..."
+3. Пользователь пишет вопрос на русском
+4. Claude решает какие инструменты вызвать и в каком порядке
+5. MCP-сервер передаёт запросы в AmoCRM API v4, возвращает JSON
+6. Claude анализирует данные и отвечает пользователю
+
+Внутри MCP-сервера нет ИИ — это прокси между Claude и AmoCRM.
+
+## Установка
+
+### Вариант A: pip (рекомендуется)
+
+```bash
+pip install amocrm-mcp
+```
+
+### Вариант B: из исходников
+
+```bash
+git clone https://github.com/ilyaberdysh/amocrm-mcp.git
+cd amocrm-mcp
+pip install -e .
+```
+
+## Настройка
+
+### 1. Создать интеграцию в AmoCRM
+
+1. AmoCRM → **Настройки** → **Интеграции** → **Создать интеграцию**
+2. Тип: **Внешняя интеграция**
+3. Redirect URI: `https://localhost`
+4. Скопировать **Client ID** и **Client Secret**
+
+### 2. Авторизоваться
+
+```bash
+amocrm-mcp-auth
+```
+
+Или если установлено из исходников:
+
+```bash
+python3 auth_setup.py
+```
+
+Скрипт спросит:
+- **Субдомен** — часть URL вашего AmoCRM (например `mycompany` из `mycompany.amocrm.ru`)
+- **Client ID** и **Client Secret** — из шага 1
+- **Redirect URI** — по умолчанию `https://localhost`
+- **Auth code** — откроется URL, авторизуетесь, скопируете `code` из URL редиректа
+
+Токены сохранятся в `~/.amocrm/config.json`.
+
+### 3. Подключить к Claude Desktop
+
+Откройте файл конфигурации:
+
+**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Добавьте:
+
+```json
+{
+  "mcpServers": {
+    "amocrm": {
+      "command": "amocrm-mcp"
+    }
+  }
+}
+```
+
+> Если установлено из исходников, укажите полный путь:
+> ```json
+> {"command": "python3", "args": ["/путь/до/amocrm-mcp/server.py"]}
+> ```
+
+### 4. Перезапустить Claude Desktop
+
+**Cmd+Q** (Mac) / **Alt+F4** (Windows) → открыть заново.
+
+В чате появится иконка инструментов — `amocrm` с 17 тулами.
+
+### 5. Проверить
+
+```
+Покажи мои воронки в AmoCRM
+```
+
+## Инструменты (17)
+
+| Инструмент | Что делает |
+|------------|-----------|
+| `get_pipelines` | Воронки продаж с этапами и их ID |
+| `get_leads` | Сделки с фильтрами (менеджер, воронка, статус, даты, сумма) |
+| `count_and_sum_leads` | Подсчёт и сумма сделок **без лимита 200** — для аналитики |
+| `get_contacts` | Контакты (поиск по имени, email, телефону) |
+| `get_companies` | Компании |
+| `get_users` | Пользователи / менеджеры |
+| `get_tasks` | Задачи (активные/выполненные, сортировка по дедлайну) |
+| `get_notes` | Примечания к сделкам, контактам, компаниям |
+| `get_events` | Журнал событий (смена этапов, создание сделок) |
+| `get_customers` | Покупатели (повторные клиенты) |
+| `get_unsorted` | Неразобранные заявки |
+| `get_catalogs` | Каталоги товаров/услуг |
+| `get_catalog_elements` | Элементы каталогов |
+| `get_custom_fields` | Пользовательские поля сущностей |
+| `get_loss_reasons` | Причины отказа |
+| `get_tags` | Теги |
+| `get_sources` | Источники трафика |
+
+## Примеры запросов
+
+```
+Сколько сделок закрыто в феврале 2025?
+Сравни продажи за этот и прошлый месяц
+Кто из менеджеров закрыл больше всего сделок?
+Покажи просроченные задачи Никиты
+Сделки на этапе "Переговоры" во всех воронках
+Найди сделки дороже 500 000 ₽ в работе
+Сколько неразобранных заявок?
+Какие кастомные поля есть у сделок?
+Причины отказа по проигранным сделкам
+```
+
+## Структура проекта
+
+```
+amocrm-mcp/
+├── server.py           # MCP-сервер — точка входа, 17 tool definitions
+├── amocrm_client.py    # AmoCRM API v4 клиент
+│                         - OAuth2 с auto-refresh токенов
+│                         - Retry на 429 (rate limit) с backoff 2s/5s/10s
+│                         - Пагинация до 10 000 записей
+│                         - Обработка пустых ответов API
+├── config.py           # Чтение/запись ~/.amocrm/config.json
+├── auth_setup.py       # CLI для первичной OAuth2 авторизации
+├── pyproject.toml      # Метаданные, зависимости, entry points
+└── QA_TEST_PROMPT.md   # QA-промпт для тестирования (10 вопросов)
+```
+
+## Токены
+
+- Хранятся в `~/.amocrm/config.json`
+- Обновляются автоматически при каждом запросе
+- Протухают если не использовать > 3 месяцев
+- Если протухли — снова запустите `amocrm-mcp-auth`
+
+## Отладка
+
+```bash
+# Проверить что сервер запускается
+amocrm-mcp
+# Если висит без ошибок — ждёт подключения (Ctrl+C для выхода)
+
+# Проверить конфиг
+cat ~/.amocrm/config.json
+
+# Логи Claude Desktop
+# Mac: ~/Library/Logs/Claude/
+# Windows: %APPDATA%\Claude\logs\
+```
+
+## Требования
+
+- Python 3.11+
+- Claude Desktop
+- Аккаунт AmoCRM с правами создания интеграций
+
+## Технологии
+
+- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol
+- AmoCRM API v4 (OAuth2)
+- Без внешних HTTP-библиотек — `urllib` из stdlib
+
+## Лицензия
+
+MIT

amocrm_mcp-0.1.0/QA_TEST_PROMPT.md

@@ -0,0 +1,128 @@
+# QA Test Prompt для AmoCRM MCP Server (v2)
+
+Скопируй весь текст ниже и вставь в Claude Desktop (или Claude Code) где подключён AmoCRM MCP.
+
+---
+
+## ПРОМПТ
+
+```
+Ты QA-тестировщик AmoCRM MCP сервера. Твоя задача — последовательно выполнить 10 тестовых запросов, записать результаты и составить итоговый QA-отчёт.
+
+ВАЖНО:
+- Каждый вопрос выполняй ОТДЕЛЬНО, дожидаясь полного ответа
+- Записывай ТОЧНЫЕ числа, суммы, количество записей из ответа
+- Если инструмент вернул ошибку — запиши текст ошибки
+- Фиксируй какие именно инструменты (tool calls) были вызваны и с какими параметрами
+
+---
+
+### ТЕСТ 1: Поиск контактов
+Вызови нужные инструменты чтобы ответить: "Покажи контакты с именем Алексей"
+Ожидание: список контактов, у каждого — имя, телефон/email если есть. Не пустой результат.
+
+### ТЕСТ 2: Компании
+Ответь: "Какие компании есть в CRM? Покажи первые 5"
+Ожидание: 5 компаний с названиями. Если есть — ответственный менеджер и количество сделок.
+
+### ТЕСТ 3: Воронки + активные сделки (MULTI-TOOL)
+Ответь: "Покажи все воронки и сколько активных сделок в каждой"
+Ожидание: таблица воронок с количеством активных сделок (exclude_closed=true). Нужно вызвать get_pipelines, затем count_and_sum_leads для каждой воронки.
+
+### ТЕСТ 4: Топ менеджер месяца (MULTI-TOOL, КРИТИЧЕСКИЙ)
+Ответь: "Кто из менеджеров закрыл больше всего сделок в этом месяце?"
+Ожидание: вызвать get_users, затем count_and_sum_leads с closed_at фильтром за текущий месяц для каждого менеджера. Результат — рейтинг менеджеров по количеству закрытых сделок.
+
+### ТЕСТ 5: Просроченные задачи менеджера (MULTI-TOOL)
+Ответь: "Покажи просроченные задачи Никиты Чуравского"
+Ожидание: найти user_id через get_users, затем get_tasks с complete_till_to=текущий unix timestamp и responsible_user_ids. Задачи должны быть отсортированы по дедлайну (просроченные первыми).
+
+### ТЕСТ 6: Причины отказа
+Ответь: "Какие причины отказа по проигранным сделкам?"
+Ожидание: список причин отказа из get_loss_reasons. Не ошибка и не пустой список.
+
+### ТЕСТ 7: События за сегодня
+Ответь: "Покажи последние события — кто что менял за сегодня"
+Ожидание: список событий из get_events(date_from=начало сегодня в unix). Тип события, кто сделал, что изменилось.
+
+### ТЕСТ 8: Неразобранные заявки
+Ответь: "Сколько нераспределённых заявок?"
+Ожидание: число из get_unsorted. Может быть 0 — это валидный результат, но не ошибка.
+
+### ТЕСТ 9: Сделки по цене (ФИЛЬТРАЦИЯ)
+Ответь: "Покажи сделки дороже 500 000 рублей в работе"
+Ожидание: сделки с price >= 500000, только активные (не закрытые). Можно использовать get_leads(price_from=500000) + исключить status 142/143, или count_and_sum_leads(price_from=500000, exclude_closed=true).
+
+### ТЕСТ 10: Кастомные поля
+Ответь: "Какие кастомные поля есть у сделок?"
+Ожидание: список полей из get_custom_fields(entity="leads"). Каждое поле — ID, название, тип.
+
+---
+
+### СОСТАВЛЕНИЕ ОТЧЁТА
+
+После всех 10 тестов составь отчёт в ТОЧНО таком формате:
+
+# QA Report — AmoCRM MCP Server — [ДАТА]
+
+## Общий результат: X/10 passed
+
+| # | Вопрос | Ожидание | Результат | Статус |
+|---|--------|----------|-----------|--------|
+| 1 | [вопрос] | [что ожидалось] | [что реально вернулось — ТОЧНЫЕ числа, данные, ошибки] | ✅ PASS / ❌ FAIL |
+| ... | ... | ... | ... | ... |
+
+## Детали по FAIL-кейсам
+
+Для каждого FAIL опиши:
+
+### BUG-N — Тест X: [краткое описание]
+**Вопрос:** [точный вопрос]
+**Что вернул:** [точный ответ с числами]
+**Что ожидалось:** [ожидаемый результат]
+**Какие инструменты вызывались:** [список tool calls с параметрами]
+**Гипотеза причины:** [почему результат неверный]
+**Рекомендация:** [что исправить в MCP-сервере]
+
+## Прочие находки
+
+Замечания, не являющиеся FAIL, но важные (аномальные данные, UX-улучшения, медленные ответы).
+
+## Критерии оценки
+
+- ✅ PASS: инструмент вернул корректные данные, нет ошибок
+- ❌ FAIL: ошибка (JSONDecodeError, timeout, пустой результат при наличии данных), неверные данные
+- ✅ PASS (с оговоркой): данные верные но есть мелкий недочёт (формат, сортировка)
+
+## Итоговый список задач
+
+| ID | Приоритет | Описание |
+|----|-----------|----------|
+| BUG-1 | 🔴 КРИТ / 🟡 СРЕДН / 🟢 НИЗК | [описание бага и что нужно исправить] |
+```
+
+---
+
+## Как использовать
+
+1. Подключи AmoCRM MCP к Claude Desktop (см. README.md)
+2. Открой новый чат в Claude Desktop
+3. Скопируй весь блок ПРОМПТ выше и вставь в чат
+4. Claude выполнит все 10 тестов и выдаст отчёт
+5. Сохрани отчёт — сравнивай между версиями сервера
+
+## Покрытие тулов
+
+| Тул | Тесты |
+|-----|-------|
+| get_contacts | 1 |
+| get_companies | 2 |
+| get_pipelines | 3 |
+| count_and_sum_leads | 3, 4, 9 |
+| get_users | 4, 5 |
+| get_tasks | 5 |
+| get_loss_reasons | 6 |
+| get_events | 7 |
+| get_unsorted | 8 |
+| get_leads | 9 |
+| get_custom_fields | 10 |

amocrm_mcp-0.1.0/README.md

@@ -0,0 +1,196 @@
+# AmoCRM MCP Server
+
+MCP-сервер для [AmoCRM](https://www.amocrm.ru/). Подключается к Claude Desktop и даёт Claude прямой доступ к вашей CRM через 17 инструментов.
+
+Задавайте вопросы на русском — Claude сам вызовет нужные API и скомбинирует ответ.
+
+## Архитектура
+
+```
+┌──────────────────┐     stdin/stdout      ┌──────────────────┐     HTTPS      ┌──────────────┐
+│  Claude Desktop  │ ◄──── MCP Protocol ──► │  amocrm-mcp      │ ◄── REST ───► │  AmoCRM API  │
+│  (LLM + UI)      │                        │  (локальный)      │                │  (облако)    │
+└──────────────────┘                        └──────────────────┘                └──────────────┘
+```
+
+**Как это работает:**
+
+1. Claude Desktop запускает `amocrm-mcp` как subprocess
+2. MCP-сервер сообщает Claude: "у меня 17 инструментов — get_leads, get_contacts..."
+3. Пользователь пишет вопрос на русском
+4. Claude решает какие инструменты вызвать и в каком порядке
+5. MCP-сервер передаёт запросы в AmoCRM API v4, возвращает JSON
+6. Claude анализирует данные и отвечает пользователю
+
+Внутри MCP-сервера нет ИИ — это прокси между Claude и AmoCRM.
+
+## Установка
+
+### Вариант A: pip (рекомендуется)
+
+```bash
+pip install amocrm-mcp
+```
+
+### Вариант B: из исходников
+
+```bash
+git clone https://github.com/ilyaberdysh/amocrm-mcp.git
+cd amocrm-mcp
+pip install -e .
+```
+
+## Настройка
+
+### 1. Создать интеграцию в AmoCRM
+
+1. AmoCRM → **Настройки** → **Интеграции** → **Создать интеграцию**
+2. Тип: **Внешняя интеграция**
+3. Redirect URI: `https://localhost`
+4. Скопировать **Client ID** и **Client Secret**
+
+### 2. Авторизоваться
+
+```bash
+amocrm-mcp-auth
+```
+
+Или если установлено из исходников:
+
+```bash
+python3 auth_setup.py
+```
+
+Скрипт спросит:
+- **Субдомен** — часть URL вашего AmoCRM (например `mycompany` из `mycompany.amocrm.ru`)
+- **Client ID** и **Client Secret** — из шага 1
+- **Redirect URI** — по умолчанию `https://localhost`
+- **Auth code** — откроется URL, авторизуетесь, скопируете `code` из URL редиректа
+
+Токены сохранятся в `~/.amocrm/config.json`.
+
+### 3. Подключить к Claude Desktop
+
+Откройте файл конфигурации:
+
+**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Добавьте:
+
+```json
+{
+  "mcpServers": {
+    "amocrm": {
+      "command": "amocrm-mcp"
+    }
+  }
+}
+```
+
+> Если установлено из исходников, укажите полный путь:
+> ```json
+> {"command": "python3", "args": ["/путь/до/amocrm-mcp/server.py"]}
+> ```
+
+### 4. Перезапустить Claude Desktop
+
+**Cmd+Q** (Mac) / **Alt+F4** (Windows) → открыть заново.
+
+В чате появится иконка инструментов — `amocrm` с 17 тулами.
+
+### 5. Проверить
+
+```
+Покажи мои воронки в AmoCRM
+```
+
+## Инструменты (17)
+
+| Инструмент | Что делает |
+|------------|-----------|
+| `get_pipelines` | Воронки продаж с этапами и их ID |
+| `get_leads` | Сделки с фильтрами (менеджер, воронка, статус, даты, сумма) |
+| `count_and_sum_leads` | Подсчёт и сумма сделок **без лимита 200** — для аналитики |
+| `get_contacts` | Контакты (поиск по имени, email, телефону) |
+| `get_companies` | Компании |
+| `get_users` | Пользователи / менеджеры |
+| `get_tasks` | Задачи (активные/выполненные, сортировка по дедлайну) |
+| `get_notes` | Примечания к сделкам, контактам, компаниям |
+| `get_events` | Журнал событий (смена этапов, создание сделок) |
+| `get_customers` | Покупатели (повторные клиенты) |
+| `get_unsorted` | Неразобранные заявки |
+| `get_catalogs` | Каталоги товаров/услуг |
+| `get_catalog_elements` | Элементы каталогов |
+| `get_custom_fields` | Пользовательские поля сущностей |
+| `get_loss_reasons` | Причины отказа |
+| `get_tags` | Теги |
+| `get_sources` | Источники трафика |
+
+## Примеры запросов
+
+```
+Сколько сделок закрыто в феврале 2025?
+Сравни продажи за этот и прошлый месяц
+Кто из менеджеров закрыл больше всего сделок?
+Покажи просроченные задачи Никиты
+Сделки на этапе "Переговоры" во всех воронках
+Найди сделки дороже 500 000 ₽ в работе
+Сколько неразобранных заявок?
+Какие кастомные поля есть у сделок?
+Причины отказа по проигранным сделкам
+```
+
+## Структура проекта
+
+```
+amocrm-mcp/
+├── server.py           # MCP-сервер — точка входа, 17 tool definitions
+├── amocrm_client.py    # AmoCRM API v4 клиент
+│                         - OAuth2 с auto-refresh токенов
+│                         - Retry на 429 (rate limit) с backoff 2s/5s/10s
+│                         - Пагинация до 10 000 записей
+│                         - Обработка пустых ответов API
+├── config.py           # Чтение/запись ~/.amocrm/config.json
+├── auth_setup.py       # CLI для первичной OAuth2 авторизации
+├── pyproject.toml      # Метаданные, зависимости, entry points
+└── QA_TEST_PROMPT.md   # QA-промпт для тестирования (10 вопросов)
+```
+
+## Токены
+
+- Хранятся в `~/.amocrm/config.json`
+- Обновляются автоматически при каждом запросе
+- Протухают если не использовать > 3 месяцев
+- Если протухли — снова запустите `amocrm-mcp-auth`
+
+## Отладка
+
+```bash
+# Проверить что сервер запускается
+amocrm-mcp
+# Если висит без ошибок — ждёт подключения (Ctrl+C для выхода)
+
+# Проверить конфиг
+cat ~/.amocrm/config.json
+
+# Логи Claude Desktop
+# Mac: ~/Library/Logs/Claude/
+# Windows: %APPDATA%\Claude\logs\
+```
+
+## Требования
+
+- Python 3.11+
+- Claude Desktop
+- Аккаунт AmoCRM с правами создания интеграций
+
+## Технологии
+
+- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol
+- AmoCRM API v4 (OAuth2)
+- Без внешних HTTP-библиотек — `urllib` из stdlib
+
+## Лицензия
+
+MIT