Planfix MCP Server
Интеграция системы управления бизнес-процессами Planfix с протоколом Model Context Protocol (MCP) для использования с Claude и другими AI-ассистентами.
Возможности
- Управление задачами: создание, поиск, обновление статусов
- Управление проектами: создание новых проектов
- Контакты: добавление новых контактов в CRM
- Аналитика: получение отчётов по времени, финансам, задачам
- Комментарии: добавление комментариев к задачам
📊 Ресурсы (Resources)
- Список проектов: активные проекты с количеством задач
- Сводка дашборда: текущее состояние рабочего пространства
- Детали задач: подробная информация по конкретной задаче
- Недавние контакты: последние добавленные контакты
- Отчёты: предварительно сформированные отчёты
💡 Промпты (Prompts)
- Анализ проектов: шаблон для анализа состояния проекта
- Еженедельные отчёты: шаблон для создания отчётов
- Планирование спринта: шаблон для планирования задач
Установка
Требования
- Python 3.8+
- uv (рекомендуется) или pip
- Аккаунт Planfix с API доступом
1. Клонирование и установка зависимостей
git clone <repository-url>
cd planfix-mcp-server
# С использованием uv (рекомендуется)
uv sync
# Или с pip
pip install -r requirements.txt
2. Настройка API ключей
Получите API ключ в вашем аккаунте Planfix:
- Перейдите в Настройки → API
- Создайте новый API ключ
Создайте файл .env:
Заполните .env файл:
PLANFIX_ACCOUNT=your-account-name
PLANFIX_API_KEY=your-api-key
3. Тестирование
# Запуск с аргументами командной строки
python -m src.planfix_server --account your-account --api-key your-api-key
# Запуск в режиме отладки
python -m src.planfix_server --debug
# Просмотр справки
python -m src.planfix_server --help
# Запуск с переменными окружения (из .env файла)
python -m src.planfix_server
Использование
После установки вы сможете:
Создание задач
Создай задачу "Подготовить презентацию" с описанием "Презентация для клиента XYZ" и приоритетом HIGH
Поиск информации
Найди все задачи по проекту "Разработка сайта"
Получение аналитики
Покажи отчёт по времени за последний месяц
Управление проектами
Создай проект "Новая маркетинговая кампания" с описанием "Q1 2024 кампания"
Конфигурация
Аргументы командной строки
Сервер поддерживает следующие аргументы командной строки:
| Аргумент | Описание | Пример |
|---|
--account | Название аккаунта Planfix | --account mycompany |
--api-key | API ключ Planfix | --api-key abc123xyz |
--debug | Включить отладочные логи | --debug |
--help | Показать справку | --help |
--version | Показать версию | --version |
Примеры использования:
# Полная конфигурация через аргументы
uv run python -m src.planfix_server --account mycompany --api-key abc123
# Запуск в режиме отладки
uv run python -m src.planfix_server --debug
# Комбинирование с переменными окружения
export PLANFIX_ACCOUNT=mycompany
uv run python -m src.planfix_server --api-key abc123
Переменные окружения
| Переменная | Описание | Обязательная |
|---|
PLANFIX_ACCOUNT | Название вашего аккаунта Planfix | ✅ |
PLANFIX_API_KEY | API ключ | ✅ |
PLANFIX_BASE_URL | Базовый URL (по умолчанию: https://{account}.planfix.ru) | ❌ |
DEBUG | Включить отладочные логи | ❌ |
Настройка в Cursor
Cursor поддерживает MCP серверы начиная с версии 0.42+. Для подключения:
- Откройте настройки Cursor:
Cmd/Ctrl + , - Найдите раздел "MCP Servers" или добавьте конфигурацию в файл настроек
- Добавьте конфигурацию сервера:
С использованием uvx:
{
"mcp.servers": {
"planfix": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/your-repo/planfix-mcp@main",
"planfix-server",
"--account", "your-account-name",
"--api-key", "your-api-key"
]
}
}
}
Или с переменными окружения:
{
"mcp.servers": {
"planfix": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/your-repo/planfix-mcp@main",
"planfix-server"
],
"env": {
"PLANFIX_ACCOUNT": "your-account-name",
"PLANFIX_API_KEY": "your-api-key"
}
}
}
}
- Альтернативный способ через .cursorrules:
Создайте файл .cursorrules в корне вашего проекта:
MCP Server: Planfix Integration
This project uses a Planfix MCP server for task and project management.
Available tools:
- search_tasks: Find tasks by query, project, assignee, or status
- search_contacts: Search for contacts and companies
- get_contact_details: Get detailed information about a contact
- list_employees: Get list of employees
- list_files: Get files associated with tasks/projects
- list_comments: Get comments for tasks/projects
- list_reports: Get available reports
- list_processes: Get business processes
Server configuration:
- Command: uvx --from git+https://github.com/your-repo/planfix-mcp@main planfix-server
- Requires PLANFIX_ACCOUNT, PLANFIX_API_KEY environment variables
Use these tools to help with project management, task tracking, and CRM operations.
- Перезапустите Cursor для применения изменений
- Проверьте подключение: В чате Cursor должны появиться доступные инструменты Planfix
Использование в Cursor
После настройки вы можете использовать Planfix прямо в чате Cursor:
Найди все активные задачи по проекту "Разработка сайта"
Покажи детали контакта с ID 123
Создай отчет по всем просроченным задачам
Устранение проблем в Cursor
- Проверьте пути: Используйте абсолютные пути к файлам
- Переменные окружения: Убедитесь, что все API ключи указаны корректно
- Логи: Проверьте вывод в консоли разработчика Cursor (
Cmd/Ctrl + Shift + I) - Версия: Убедитесь, что используете Cursor 0.42 или новее
Разработка
Структура проекта
planfix-mcp-server/
├── src/
│ ├── planfix_server.py # Основной MCP сервер
│ ├── planfix_api.py # API клиент для Planfix
│ ├── config.py # Конфигурация
│ └── utils.py # Вспомогательные функции
├── tests/
│ ├── test_server.py # Тесты сервера
│ ├── test_api.py # Тесты API
│ └── conftest.py # Конфигурация pytest
├── examples/
│ ├── basic_usage.py # Примеры использования
│ └── advanced_workflows.py # Сложные сценарии
├── docs/
│ ├── api_reference.md # Справочник по API
│ └── troubleshooting.md # Решение проблем
├── .env.example # Пример конфигурации
├── requirements.txt # Зависимости
├── pyproject.toml # Конфигурация проекта
└── README.md # Документация
Запуск тестов
# Все тесты
uv run pytest
# С покрытием кода
uv run pytest --cov=src
# Только быстрые тесты
uv run pytest -m "not slow"
Линтинг и форматирование
# Форматирование кода
uv run ruff format
# Проверка стиля
uv run ruff check
# Проверка типов
uv run mypy src/
Примеры использования
Автоматизация рабочих процессов
# Создание еженедельного планирования
tasks = await search_tasks(status="active", assignee_id=123)
report = await get_analytics_report("time", "2024-01-01", "2024-01-07")
Интеграция с другими системами
# Синхронизация с внешними сервисами
contact = await add_contact("Новый клиент", "client@example.com")
project = await create_project(f"Проект для {contact.name}")
API Reference
Подробная документация по всем доступным инструментам, ресурсам и промптам находится в docs/api_reference.md.
Устранение неполадок
Общие проблемы и их решения описаны в docs/troubleshooting.md.
Лицензия
MIT License - см. LICENSE файл.
Поддержка
- GitHub Issues: для сообщений об ошибках и запросов функций
- MCP Documentation: https://modelcontextprotocol.io/
Changelog
v1.0.1 (2024-12-23)
- Улучшена обработка аргументов командной строки с использованием argparse
- Добавлены опции --help, --version, --debug
- Убраны эмодзи и markdown форматирование из вывода инструментов
- Упрощен возврат данных через model_dump() для лучшей интеграции
- Удалена зависимость от PLANFIX_USER_KEY (только PLANFIX_ACCOUNT и PLANFIX_API_KEY)
- Обновлена конфигурация для Cursor с использованием uvx и git+repo@main
- Удалена секция Claude Desktop из документации
v1.0.0 (2024-12-23)
- Первый релиз
- Базовые операции с задачами и проектами
- Интеграция с аналитикой Planfix
- Поддержка управления контактами