MCP-сервер Simpro

Неофициальный. Это независимый сторонний проект. Он не связан с Simpro, не одобрен и не поддерживается компанией Simpro.

Позволяет ИИ-агенту работать с вашим аккаунтом Simpro. Искать практически что угодно в Simpro, собирать данные, для которых обычно пришлось бы кликать по нескольким экранам. Вы задаёте вопрос на обычном английском; агент выполняет поиск и изменения в Simpro за вас.

Он охватывает все части API Simpro, так что даже если нет специально созданного инструмента для чего-то, агент всё равно может до этого добраться.

⚠️ Этот инструмент может записывать и удалять, а не только читать. Он обращается ко всему API Simpro, включая конечные точки, которые обновляют и удаляют записи. Управляющий им ИИ-агент может — по ошибке или следуя плохой инструкции — изменить или уничтожить котировки, заказы, клиентов, элементы каталога и многое другое в вашем рабочем аккаунте Simpro, массово, без возможности отмены. Он действует с теми правами, которые есть у ключа или логина, которые вы ему даёте. Не передавайте его агенту, которому вы не доверяете, не позволяйте ему работать без присмотра против продакшена и дайте ему логин/ключ Simpro с правами только на то, что ему действительно нужно. Если вам нужна безопасность только для чтения, создайте пользователя Simpro с правами только для чтения и выполняйте аутентификацию от его имени.

Это было разработано на основе внутреннего инструмента, который мы используем за нашим собственным MCP Gateway. Мы добавили несколько дополнительных функций, чтобы сделать его более функциональным для сообщества, но режимы mcbp и OAuth Broker не используются нами внутри.

Это программное обеспечение предоставляется «как есть», без каких-либо гарантий, явных или подразумеваемых. Вы используете его на свой страх и риск; авторы не несут ответственности за любые потери, ущерб или изменения, внесённые в ваши данные Simpro в результате его использования.

Предварительные требования

• Для установки в Claude Desktop (вариант 1): только Claude Desktop и OAuth-приложение Simpro — пакет .mcpb содержит собственную среду выполнения.

• Для запуска из исходников или самостоятельного хостинга (варианты 2 и 3): Node.js 24 или новее и npm.

• Сборка Simpro, к которой вы можете подключиться, и OAuth-приложение (или устаревший API-ключ), созданное в ней — в разделе каждого режима указано, что именно ему нужно.

Related MCP server: ServiceTitan MCP Server

Содержание

• Установка в Claude Desktop (простой способ)

  • Что нужно от Simpro

  • Установка

  • Вход (поток OAuth)

  • Другие способы аутентификации

  • Запуск локально из исходников

• Режим OAuth Broker (для коннектора ИИ-агента)

• Режим HTTP-прокси (для общей/хостинговой настройки)

• Какой режим мне нужен?

• Подключение клиента (фрагменты конфигурации)

• Как брокер улучшает вход в Simpro

• Сборка самостоятельно

1. Установка в Claude Desktop (простой способ)

Никакой командной строки, никаких файлов настройки. Вы устанавливаете пакет .mcpb из настроек расширений Claude Desktop, заполняете короткую форму и один раз входите в Simpro в браузере. После этого агент остаётся в системе, и вы просто общаетесь.

Что нужно от Simpro

Вы аутентифицируетесь с помощью OAuth-приложения Simpro, которое выполняет вход через собственный экран входа Simpro — это рекомендуемый способ. Создайте его в Simpro в разделе Setup → Integrations → API → New API Key (выберите приложение OAuth / «Authorization Code»), затем запишите:

Один важный шаг: в вашем OAuth-приложении Simpro установите Redirect URI на http://localhost:8237/callback. Именно сюда Simpro вернёт вас после входа. Он должен совпадать точно. Если порт 8237 уже занят на вашей машине, выберите другой и укажите соответствующий Auth redirect port на экране установки — но зарегистрированный redirect URI должен использовать тот же порт.

Установка

1. Скачайте последний файл simpro-mcp-server.mcpb со страницы релизов.

2. В Claude Desktop откройте Settings → Extensions, нажмите Advanced settings, затем Install extension (возможно, сначала потребуется включить там установку расширений для разработчиков/расширений). Выберите скачанный файл simpro-mcp-server.mcpb. Появится экран установки.

3. Заполните:

   • Build URL и Company ID

   • Authentication mode — оставьте authorization_code (вход через браузер).

   • Client ID и Client secret из вашего OAuth-приложения Simpro.

   • Оставьте Auth redirect port равным 8237, если вы не зарегистрировали другой.

4. Нажмите «Установить».

Вход (поток OAuth)

При первом использовании инструмента агентом в браузере откроется вкладка с экраном входа в Simpro. Войдите и подтвердите доступ. На вкладке появится «✓ Authorised» — закройте её и вернитесь к чату.

Этого одного входа достаточно. Инструмент кэширует refresh-токен, поэтому он остаётся в системе между перезапусками, и вас не будут спрашивать снова, пока этот токен не будет отозван или не истечёт. Если это когда-нибудь произойдёт, он просто снова откроет вкладку входа.

Вот и всё — начните чат и спросите что-то вроде "покажи открытые котировки для Acme" или "что на заказе 4521?".

Page size — необязательная настройка на экране установки. Оставьте 50. Она просто ограничивает количество строк, возвращаемых за раз, чтобы большие списки не перегружали один ответ — агент всегда может запросить больше.

Другие способы аутентификации

Поле Authentication mode на экране установки предлагает три варианта:

Безопасность ваших учётных данных

Ваш client secret, refresh-токен и любой API-ключ хранятся Claude Desktop и используются только для связи с вашей собственной сборкой Simpro. Любой, у кого они есть, может действовать в Simpro с теми же правами, которые вы предоставили, поэтому не передавайте установку .mcpb или эти значения людям, у которых не должно быть такого доступа. Если учётные данные когда-либо были раскрыты, отзовите OAuth-приложение или ключ в Simpro и создайте новое.

Запуск локально из исходников

Для разработчиков или тех, кто запускает из Git-клона вместо пакета .mcpb. Если вы установили расширение выше, этот раздел можно пропустить.

1. Скопируйте .env.example → .env и задайте SIMPRO_BASE_URL и SIMPRO_COMPANY_ID, а также либо SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET (для входа через браузер или машинного входа) либо SIMPRO_API_KEY (устаревший ключ).

2. Режим аутентификации определяется автоматически из того, что вы задали — client_credentials, если присутствуют и client ID, и secret, иначе api_key. Чтобы принудительно использовать вход через браузер, задайте SIMPRO_AUTH_MODE=authorization_code.

3. npm install && npm run build && npm start — это работает через stdio, так же, как установленное расширение.

Для входа через браузер (authorization_code) вы можете один раз войти заранее с помощью npm run login — он откроет вкладку входа в Simpro и закэширует refresh-токен в .simpro-tokens.json. Если пропустить этот шаг, сервер просто выполнит тот же вход при первом использовании инструмента. Полный список скриптов см. в разделе Сборка самостоятельно.

2. Режим OAuth Broker (для коннектора ИИ-агента)

Для подключения Simpro к ИИ-агенту как полноценного коннектора, где каждый человек входит в Simpro сам через обычный экран входа Simpro — без общего ключа, без файла настройки на каждого человека. Для большинства людей, запускающих это на сервере, это тот режим, который вам нужен.

Именно этот режим используется в предоставленной Docker-настройке по умолчанию. Это более безопасный вариант по умолчанию: сервер сам аутентифицирует пользователей, а не доверяет учётным данным, переданным ему извне. Он всё равно должен находиться за обратным прокси, который завершает TLS и маршрутизирует PUBLIC_URL на него — но контейнер никогда не решает, доверять ли входящему заголовку.

Собственный вход Simpro — это дизайн OAuth 2.0, к которому современные коннекторы агентов не подключаются напрямую. Этот сервер находится посередине и приводит его к стандарту OAuth 2.1, который они требуют — добавляя шаги безопасности, которых не хватает Simpro, при этом передавая реальный вход в Simpro. С точки зрения пользователя это просто «нажмите подключить, войдите в Simpro». Точные шаги, которые он добавляет, описаны в разделе Как брокер улучшает вход в Simpro ниже.

Сервер находится перед Simpro и выполняет рукопожатие входа. Пользователь добавляет коннектор в своём агенте, его отправляют в Simpro для входа, и с этого момента агент действует как этот человек в Simpro. Его доступ к Simpro запечатан внутри токена, который хранит агент; сервер не ведёт базу данных входов.

Этот режим требует публичного веб-адреса и OAuth-приложения Simpro (созданного в Simpro в разделе Setup → Integrations). В этом OAuth-приложении установите Redirect URL на ваш публичный адрес с добавлением /callback — например https://simpro.yourcompany.com/callback.

Настройки

Задайте их как переменные окружения, в дополнение к SIMPRO_BASE_URL (и, при необходимости, SIMPRO_COMPANY_ID) из предыдущего раздела.

Не задавайте SIMPRO_API_KEY в этом режиме — сервер откажется запускаться.

3. Режим HTTP-прокси (для общего/хостингового развёртывания)

Для команд, запускающих это на сервере за чем-то, что уже обрабатывает вход пользователей (например, в окружении Cowork или Copilot). В этом режиме сервер не хранит никакого собственного ключа Simpro — каждый запрос несёт свой собственный логин, добавляемый тем, кто выполняет вход пользователей. Сервер просто пропускает его дальше к Simpro.

⚠️ Не предназначен для прямого доступа из интернета. Этот режим должен работать за шлюзом или обратным прокси (MCP-шлюз, Context Forge или что-то вроде nginx/Traefik), который завершает TLS и аутентифицирует пользователей. Он не выполняет собственную аутентификацию и не защищён для прямого доступа — никогда не публикуйте его напрямую в интернет. Контейнер намеренно не публикуется на хосте по умолчанию; шлюз обращается к нему через частную сеть.

Чтобы использовать этот режим, установите SIMPRO_TRANSPORT=proxy (прилагаемая настройка Docker по умолчанию использует более безопасный режим брокера выше). Если вы развёртываете с помощью Portainer или Context Forge, см. docs/deploy.md с описанием структуры стека.

Здесь вы не задаёте API-ключ — более того, сервер откажется запускаться, если он присутствует, потому что в этом режиме только логин каждого пользователя должен предоставлять доступ.

Важно: этот режим не выполняет никаких собственных проверок. Любой заголовок Authorization, приходящий с запросом, передаётся напрямую в Simpro без изменений. Сервер не проверяет, действительны ли учётные данные, не истёк ли их срок и не поступил ли запрос от того, кому разрешено его отправлять, — только Simpro решает, работают ли учётные данные. Это сделано намеренно: режим предполагает, что уровень перед ним (шлюз или система входа) уже аутентифицировал пользователя и добавил заслуживающий доверия заголовок. Запускайте этот режим только за таким уровнем. Если вы откроете к нему прямой доступ, любой, кто сможет до него добраться, сможет передать свой заголовок в Simpro как есть.

Настройки

Они задаются как переменные окружения (в вашем файле .env или через платформу контейнеров).

Не задавайте SIMPRO_API_KEY в этом режиме — сервер откажется запускаться.

Вы также можете настроить, сколько данных возвращается за раз:

4. Какой режим мне нужен?

5. Подключение клиента (примеры конфигурации)

Установка .mcpb для Claude Desktop (вариант 1) сама записывает свою конфигурацию — для этого вам не придётся трогать JSON. Эти примеры предназначены для запуска из клонированного исходного кода или направления клиента на размещённый брокер/прокси.

Claude Desktop — stdio из исходников

Отредактируйте claude_desktop_config.json (Settings → Developer → Edit Config). Укажите command как node, а args — на собранный dist/index.js, и передайте настройки Simpro как env:

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Сначала соберите проект (npm install && npm run build). В Windows используйте полный путь с экранированными обратными слешами ("C:\\path\\to\\simpro-mcp\\dist\\index.js"). Для старого ключа уберите client id/secret и вместо них задайте "SIMPRO_API_KEY" (только для stdio).

Claude Code — claude mcp add

Зарегистрируйте тот же stdio-сервер из CLI (запустите из каталога исходников или используйте абсолютный путь):

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

Направление клиента на размещённый брокер (вариант 2)

Когда брокер запущен за вашим публичным адресом, добавьте его как удалённый коннектор — здесь нет локальной команды и переменных окружения. Используйте интерфейс коннектора / «Add custom connector» в вашем клиенте и укажите MCP URL:

https://simpro.yourcompany.com/mcp

Клиент отправляется в Simpro для входа; больше ничего настраивать не нужно. (HTTP-прокси из варианта 3 достигается так же, но ожидает, что ваш шлюз добавит bearer-токен — его нельзя добавить как простой коннектор.)

6. Как брокер модернизирует вход в Simpro

Этот раздел для технически любопытных или тех, кто проверяет безопасность коннектора. Он не нужен для использования любого из трёх режимов выше.

Современные коннекторы агентов подключаются только к серверам авторизации, соответствующим требованиям OAuth 2.1. OAuth Simpro не поддерживает PKCE и не поддерживает схемы идентификации клиентов, используемые этими коннекторами. Вместо того чтобы просить Simpro измениться, брокер выступает перед ним как собственный совместимый сервер авторизации OAuth 2.1 и незаметно ретранслирует запросы в Simpro за кулисами. В частности, он добавляет:

• PKCE (S256), применяемый нами. Подключающийся клиент должен отправить code challenge на /authorize и подтвердить его на /token; при несовпадении запрос отклоняется. Сам Simpro не выполняет PKCE, поэтому фактическим контролёром выступает брокер — устраняя разрыв, связанный с кражей кода авторизации, который оставляет открытым обычный OAuth 2.0.

• Современная идентификация клиента — без общего секрета, встроенного в клиент. Подключающийся клиент сообщает брокеру, кто он, одним из двух стандартных способов, и брокер принимает тот, который использует данный клиент:

  • CIMD (документ метаданных идентификатора клиента): client_id — это URL, который брокер загружает и проверяет при каждом запросе; он должен быть самореферентным и содержать точный адрес перенаправления, используемый в данный момент. Ничего заранее не регистрируется. Загрузка выполняется под защитой от SSRF, чтобы этот URL нельзя было использовать для зондирования внутренней сети сервера.

  • DCR (динамическая регистрация клиента, RFC 7591): клиент может POST /register, чтобы заранее выпустить собственный client_id. Брокер публикует эту конечную точку в своих метаданных. Регистрация открыта (без аутентификации), поэтому она ограничена по частоте и размеру и при достижении предела вытесняет самые старые записи; зарегистрированные клиенты сохраняются, поэтому переживают перезапуск. Клиент может зарегистрироваться как публичный (без секрета) или конфиденциальный (брокер выдаёт секрет и затем требует его на этапе получения токена).

• Точное совпадение адреса перенаправления. Адрес, на который возвращается клиент, должен совпадать с зарегистрированным символ в символ — не просто «начинается с».

• Недолговечные токены, привязанные к аудитории. Токен, который получает клиент, выпускается брокером, снабжён сроком действия и привязан к этому конкретному серверу в качестве аудитории. Настоящие токены Simpro зашифрованы (запечатаны) внутри него. Брокер не хранит базу токенов — каждый токен самодостаточен, — а выпускаемый им refresh-токен имеет ограниченный срок жизни 30 дней, так что утёкший токен нельзя бесконечно воспроизводить. Единственное исключение: поскольку Simpro ротирует refresh-токены при использовании (каждое обновление сжигает старый), брокер хранит текущий вышестоящий refresh-токен для каждого входа только в памяти в течение нескольких минут, чтобы клиент, потерявший ответ с refresh-токеном, не был вынужден снова входить в систему. Он никогда не записывается на диск; следующее успешное обновление — подтверждающее, что клиент теперь владеет текущим токеном, — удаляет его, а перезапуск или несколько минут простоя очищают его.

Итоговый эффект: агент общается с чем-то, что выглядит как чистый современный провайдер OAuth 2.1, пользователь по-прежнему входит в систему на настоящем экране Simpro, а слабые места процесса Simpro усиливаются в промежуточном звене. Весь обмен увязывается только в памяти на несколько секунд, пока длится рукопожатие, поэтому этот режим должен работать как одиночный экземпляр — не помещайте его за балансировщиком нагрузки.

Сборка самостоятельно

Если вы работаете с кодом, а не просто используете его:

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login запускает скомпилированный dist/login.js, поэтому сначала выполните сборку; для него необходимо, чтобы были заданы SIMPRO_CLIENT_ID и SIMPRO_CLIENT_SECRET (см. Запуск локально из исходного кода выше).

Имеется набор модульных тестов (npm test), покрывающий чистые детерминированные части — ранжирование поиска, форматирование вывода, пути позиций и вспомогательные функции криптографии/хранения для аутентификации. Линтера нет, и ничто не имитирует сеть, поэтому полная проверка изменения по-прежнему означает сборку и проверку на реальном аккаунте Simpro. Заметки по архитектуре и особенности API Simpro, которые стоит знать, находятся в CLAUDE.md.