MCP4Acumatica

Отказ от ответственности: Этот проект является независимой интеграцией, созданной сообществом, и не связан с Acumatica, Inc., не одобрен и не поддерживается ею. «Acumatica» является зарегистрированной торговой маркой Acumatica, Inc. Использование названия и API Acumatica осуществляется только в целях совместимости.

Удаленный сервер Model Context Protocol (MCP), который подключает Claude к Acumatica ERP 2025 R2. Работает на Cloudflare Workers с аутентификацией OAuth для каждого пользователя, направленной на ваш экземпляр Acumatica.

Каждый пользователь аутентифицируется со своими собственными учетными данными Acumatica. Его роль в Acumatica определяет, к каким записям он имеет доступ. Сервер MCP дополнительно требует определенную роль Acumatica для доступа, показывает экран согласия и автоматически скрывает конфиденциальные поля, прежде чем данные попадут к модели ИИ.

Возможности

• 49 инструментов — 38 для просмотра (только чтение) + 6 утилит/обнаружения + 4 для работы со схемой + 1 для записи (создание/обновление клиентов, отключено по умолчанию) (см. Доступные инструменты)

• Индивидуальный OAuth — пользователи входят со своими учетными данными Acumatica (или SSO)

• Контроль доступа на основе ролей — модель безопасности Acumatica определяет, что видит каждый пользователь

• Шлюз доступа — к серверу могут подключиться только те пользователи, которые могут прочитать специально предназначенный для проверки универсальный запрос Generic Inquiry (ограничьте его по своему усмотрению; рекомендуемый способ — роль-маркер, например MCP Access)

• Экран согласия — пользователи должны подтвердить обработку данных ИИ перед доступом к инструментам

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

• Ограничение частоты запросов — по умолчанию 3 одновременных запроса и 40 запросов в минуту на пользователя; оба значения можно настроить из консоли администратора. Запрос, который обнаруживает, что все слоты заняты, коротко ждет, пока один не освободится, вместо того чтобы сразу отказать; отказ возвращает структурированный конверт { error: "rate_limited", retryAfterSeconds, actionRequired }, сообщающий ИИ точное время ожидания, чтобы не повторять запрос в цикле.

• Отказ от пагинации — инструменты списков/запросов возвращают структурированный конверт { truncated, paginationSupported: false, actionRequired }, когда результаты достигают лимита записей, давая ИИ указание попросить пользователя задать более узкий фильтр, а не вызывать инструмент снова.

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

• Консоль администратора — веб-интерфейс администратора по адресу /docs/admin для просмотра логов и управления настройками среды выполнения без повторного развертывания.

• Долгосрочное хранение логов — хранение логов на базе R2 через Cloudflare Logpush с просмотрщиком логов с возможностью поиска.

Related MCP server: MCP4Acumatica

Архитектура

Claude (claude.ai / Desktop / API)
    |
    v  MCP over streamable-http
+----------------------------------+
|  Cloudflare Worker               |
|  OAuth 2.1 Provider              |
|    /authorize -> Acumatica login |
|    /callback  <- Acumatica       |
|    (access gate + OIDC userinfo) |
|    /consent   -> AI data consent |
|    /token, /register (DCR)       |
|    /mcp -> McpAgent DO (49 tools)|
+---------------+------------------+
                |  Bearer token (per-user)
                v
        Acumatica 25R2 SaaS
        Contract-Based REST API
        Default/25.200.001

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

• Node.js >= 18

• Аккаунт Cloudflare (тарифный план Workers с поддержкой Durable Objects)

• Экземпляр Acumatica 2025 R2 со следующим:

  • Подключенное приложение (Connected Application), настроенное в SM303010 с потоком OAuth 2.0 Authorization Code (области передаются сервером в запросе, не настраиваются в приложении)

  • URI перенаправления, указывающий на конечную точку вашего worker'а /callback

  • Универсальный запрос MCPAccess (SM208000) — тривиальный проверочный GI с включенным Expose via OData; шлюз входа проверяет, может ли пользователь читать его (см. Документацию по архитектуре для подробностей). Имя GI настраивается через ACUMATICA_CANARY_GI.

  • Способ ограничить, кто может читать этот GI — рекомендуется назначать только разрешенным пользователям роль-маркер MCP Access (SM201005).

Настройка

Существует три пути установки. Все они зависят одних и тех же предварительных требований на стороне Acumatica — сначала выполните их (см. раздел «Настройка Acumatica» ниже), независимо от выбранного пути.

Путь A — Кнопка «Развернуть в Cloudflare» (без терминала)

Кнопка форкает этот репозиторий в ваш аккаунт GitHub, читает wrangler.jsonc, автоматически создает пространство имен KV и корзину R2, запрашивает секреты и развертывает. Пошагово:

1. Нажмите кнопку. Cloudflare попросит вас войти (или создать аккаунт) и авторизовать форк GitHub.

2. Подтвердите привязки. Вас попросят создать пространства имен KV дважды — один раз для привязки TOKEN_STORE (данные приложения: токены, состояние OAuth, кэш, конфигурация, сессии администратора) и один раз для OAUTH_KV (используется библиотекой OAuth внутренне). Это ожидаемо: это две разные привязки, которые никогда не обмениваются ключами.

   ⚠️ Дайте двум пространствам имен разные имена (например, mcp4acumatica-app для TOKEN_STORE и mcp4acumatica-oauth для OAUTH_KV). Автоматическое предоставление Cloudflare выводит заголовок по умолчанию из имени Worker'а, поэтому оба поля по умолчанию имеют значение mcp4acumatica — и создание двух пространств имен с одинаковым названием завершается ошибкой «Cannot provision a KV Namespace with the title … because it already exists.» Если вы уже столкнулись с этой ошибкой, осталось наполовину созданное пространство имен: перейдите в Storage & Databases → KV и удалите осиротевшее пространство имен mcp4acumatica, затем повторите попытку с двумя разными именами. (Автоматическое предоставление Cloudflare не может указать обе привязки на одно пространство имен, а конфигурация не может предустановить разные заголовки — поэтому два отдельных пространства имен с разными именами — это правильный путь. Если графический интерфейс продолжает выдавать ошибку, используйте путь установки через терминал ниже: setup.sh создает одно пространство имен и привязывает к нему обе привязки.)

   Корзины R2 (mcp4acumatica-logs, mcp4acumatica-index) создаются таким же образом, но их имена фиксированы в wrangler.jsonc, поэтому они не конфликтуют.

3. Установите секреты. При запросе вставьте:

   • ACUMATICA_CLIENT_ID — из вашего Подключенного приложения (SM303010)

   • ACUMATICA_CLIENT_SECRET — с того же экрана

   • COOKIE_ENCRYPTION_KEY — откройте консоль браузера на любой странице и выполните:

     [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')

     Скопируйте полученную 64-символьную шестнадцатеричную строку.

   • ADMIN_SECRET — любой пароль, который вы запомните (защищает консоль /docs/admin). Сгенерируйте его с помощью [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join(''), если у вас нет предпочтений.

4. Разверните. Cloudflare подключает форк к Workers Builds и отправляет первое развертывание.

5. Обновите переменные Acumatica. После завершения развертывания откройте Workers & Pages → mcp4acumatica → Settings → Variables and Secrets в панели управления Cloudflare и отредактируйте:

   • ACUMATICA_URL (например, https://yourcompany.acumatica.com)

   • ACUMATICA_TENANT (компания для входа)

   • По желанию: ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP Нажмите Save and Deploy — Cloudflare переразвернет с новыми значениями.

6. Добавьте URI перенаправления в ваше Подключенное приложение. Теперь ваш worker доступен по адресу https://mcp4acumatica.<your-account>.workers.dev. Добавьте https://<that-host>/callback в URI перенаправления на экране SM303010 в Acumatica. (Чтобы использовать собственный домен, см. раздел «Собственный домен» ниже.)

7. Проверьте развертывание. Перейдите по адресу https://<your-host>/docs/admin/preflight, войдите с помощью ADMIN_SECRET и запустите диагностику предварительной проверки. Она проверяет подключение к Acumatica, конечную точку обнаружения OIDC, учетные данные Подключенного приложения, путь к арендатору и версию API контракта — любая неправильная конфигурация называется по имени.

После этого Claude может подключиться (см. раздел «Подключение Claude» ниже).

Путь B — Однострочный установщик (терминал)

Если у вас уже есть git, node и npm, выполните:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh | bash

Это клонирует репозиторий, устанавливает зависимости и запускает ./setup.sh. Сценарий установки запросит значения Acumatica, которые вы должны предоставить (URL, арендатор, идентификатор клиента и секрет Подключенного приложения), автоматически сгенерирует криптографические секреты, создаст пространство имен KV и корзину R2, загрузит секреты, развернет и запустит предварительную проверку.

Если вы предпочитаете сначала просмотреть сценарий:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh -o install.sh
less install.sh   # read it
bash install.sh   # then run

Путь C — Ручная настройка (терминал)

1. Клонирование и установка

git clone https://github.com/hallboys/MCP4Acumatica.git
cd MCP4Acumatica
npm install

2. Создание пространства имен KV

npx wrangler kv namespace create TOKEN_STORE

Запомните ID пространства имен из вывода — вы вставите его в wrangler.jsonc на следующем шаге. Тот же ID используется для обеих привязок TOKEN_STORE и OAUTH_KV.

3. Настройка wrangler

wrangler.jsonc отслеживается в репозитории как шаблон развертывания. Отредактируйте его и заполните:

• ID пространства имен KV из шага 2 (обе привязки TOKEN_STORE и OAUTH_KV — один и тот же id)

• ACUMATICA_URL — URL вашего экземпляра Acumatica (например, https://yourcompany.acumatica.com)

• ACUMATICA_TENANT — ваша компания/арендатор Acumatica

Чтобы ваши локальные значения не отображались в git status (чтобы вы по-прежнему могли без конфликтов получать обновления):

git update-index --skip-worktree wrangler.jsonc

4. Установка секретов

npx wrangler secret put ACUMATICA_CLIENT_ID
npx wrangler secret put ACUMATICA_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # use `openssl rand -hex 32`
npx wrangler secret put ADMIN_SECRET                # any password — protects /docs/admin

5. Развертывание

npx wrangler deploy

6. Локальная разработка (опционально)

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Acumatica credentials
npx wrangler dev

Настройка Acumatica

Эти шаги необходимы независимо от выбранного пути установки. Их нельзя автоматизировать — API Acumatica не предоставляет к ним доступа.

Подключенное приложение (SM303010)

1. В Acumatica: System > Integration > Connected Applications (SM303010).

2. Создайте новое Подключенное приложение.

3. Установите OAuth 2.0 Flow в Authorization Code.

4. Добавьте URI перенаправления: https://<your-worker-url>/callback (используйте имя хоста *.workers.dev или ваш собственный домен).

5. Запомните Client ID и Client Secret — вы предоставите их как секреты при развертывании.

Здесь нет поля для настройки областей. Области OAuth (api openid profile email offline_access, включая offline_access, который позволяет Acumatica выдавать токены обновления) отправляются сервером MCP в запросе авторизации — они не устанавливаются на Подключенном приложении.

Шлюз доступа: проверочный универсальный запрос (SM208000, SM201005)

Прежде чем пользователь сможет получить доступ к инструментам ИИ, процесс входа выполняет шлюз доступа: он запрашивает тривиальный проверочный Generic Inquiry через OData и проверяет, может ли токен пользователя читать его (200 → разрешено, 403 → запрещено). Сервер никогда не проверяет членство в ролях Acumatica — он только спрашивает «видите ли вы этот один GI?». Вы ограничиваете, кто может читать проверочный GI, как предпочитает ваша модель безопасности; роль-маркер — рекомендованный, самый чистый способ.

1. Создайте проверочный GI: System > Customization > Generic Inquiry (SM208000) → создайте GI с именем MCPAccess с любым тривиальным запросом (один столбец из любой таблицы подойдет). Включите Expose via OData.

2. Ограничьте, кто может читать его (рекомендуется: роль-маркер): System > Access Rights > User Roles (SM201005) → создайте роль с именем MCP Access без прав на экраны, назначьте GI MCPAccess только этой роли, затем назначьте роль каждому пользователю, который должен иметь доступ к ИИ-ассистенту. Любой другой механизм, контролирующий доступ на чтение OData к GI, также работает.

Имя проверочного GI настраивается через переменную ACUMATICA_CANARY_GI (по умолчанию MCPAccess). Отредактируйте ее в панели управления Cloudflare (Variables and Secrets) или в wrangler.jsonc.

Предоставление Generic Inquiry доступа к ИИ (настоятельно рекомендуется)

В зрелом инстансе Acumatica могут быть сотни Generic Inquiries, большинство из которых создано для человеческих экранов (широкие отчётные таблицы, дашборды, разовые запросы). Предоставление всех их ассистенту перегружает его контекст и заставляет выбирать неправильный запрос — и, что хуже, параметризованный GI, доступный через OData, возвращает незаметно неверные данные: при запросе без параметров Acumatica возвращает строки по умолчанию/без фильтрации без ошибки, которую модель не может обнаружить. Шлюз доступа к GI превращает это в opt-in: вы помечаете те GI, которые действительно полезны и корректны для запроса AI-агентом (ExposedToMCP), и модель видит только их.

Шлюз неактивен, пока вы его не настроите — сервер работает, но без реестра ассистент не может обнаруживать GI (acumatica_list_generic_inquiries ничего не возвращает; пользователь всё ещё может запустить GI по точному имени). Настройка даёт ассистенту курируемый набор, который он может безопасно обнаруживать. Включение — это разовый проект настройки Acumatica: включённый в acumatica/, он добавляет пользовательские поля UsrExposedToMCP / UsrAIDescription (GIDesign) и UsrResAIDescription (GIResult), а также изменения формы SM208000; далее следуют фиды GI MCPGIs / MCPGIFields, доступ на чтение фидов для роли MCP Access и пометка GI, которые вы хотите раскрыть. См. docs/generic-inquiries.md.

См. Generic Inquiries для полного обоснования, как решить, какие GI раскрывать, и пошаговой настройки.

Пользовательский домен (необязательно)

Развёртывание даёт вам имя хоста *.workers.dev из коробки. Чтобы подключить фирменное имя хоста:

• Через панель Cloudflare: Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add. Зона домена должна находиться в вашем аккаунте Cloudflare.

• Через wrangler.jsonc: раскомментируйте блок routes в начале файла, измените pattern и zone_name, повторно разверните.

Если вы меняете имена хостов, не забудьте добавить новый https://<host>/callback в URI перенаправления вашего Connected Application в SM303010.

Подключение Claude

Claude.ai / Claude Desktop

1. Перейдите в Settings > Connectors

2. Нажмите Add Connector и введите URL: https://<your-worker-url>/mcp

3. При первом использовании вы будете перенаправлены на страницу входа в Acumatica

4. Если ваш аккаунт может читать canary GI (т.е. вам предоставлен доступ), вы увидите страницу согласия с объяснением обработки данных ИИ

5. После подтверждения согласия Claude получит доступ ко всем 49 инструментам

Claude Code (CLI)

claude mcp add acumatica-erp --transport streamable-http https://<your-worker-url>/mcp

API (через Anthropic SDK)

При использовании Anthropic API с MCP укажите MCP-клиенту адрес https://<your-worker-url>/mcp. Сервер поддерживает OAuth 2.1 с динамической регистрацией клиентов на /register.

Доступные инструменты

Основные

Финансы / Бухгалтерия

Запасы и склад

Закупки

Проекты

Обслуживание и выездная работа

Продажи и CRM

Отгрузка и выполнение заказов

HR и расчёт зарплаты

CRM-активности

Утилиты / Обнаружение

Совет: Сначала используйте acumatica_describe_entity для обнаружения доступных полей, затем acumatica_list_entities для поиска/фильтрации. Для Generic Inquiries используйте acumatica_list_generic_inquiries для поиска имён GI и acumatica_describe_inquiry для просмотра доступных полей. См. docs/example-prompts.md для примеров использования.

Документация

Подробная документация доступна в папке docs/:

• Справочник по инструментам -- Полная спецификация всех 49 инструментов с параметрами и конечными точками

• Примеры запросов -- Примеры запросов для Claude и других MCP-клиентов, сгруппированные по сценариям использования

• Руководство по OData-фильтрации -- Руководство по параметрам запроса $filter, $orderby, $select, $expand и $top

• Generic Inquiries -- Почему GI ограничены для использования ИИ, какие GI раскрывать и как включить реестр на основе opt-in

• Знание схем -- Офлайн-инструменты обнаружения схем для создания интеграций/настроек и как строится индекс схем

• Архитектура -- Подробная архитектура, поток OAuth, модель безопасности и проектные решения

• Руководство по самостоятельному размещению -- Как запустить MCP-сервер на Node.js или других платформах вне Cloudflare

• Обновление Acumatica -- Шаги, которые необходимо предпринять при изменении или обновлении подключённой версии Acumatica

Навыки

Переиспользуемые навыки Claude, поставляемые с этим репозиторием, в skills/:

• acumatica-gi-descriptions -- Полный процесс написания ориентированных на ИИ описаний для Generic Inquiries и их результирующих колонок, основанный на собственных метаданных дизайна GI (таблицы, соединения, условия WHERE, колонки), а не на предположениях по именам. Включает платформенные ловушки, из-за которых массовая работа с метаданными GI незаметно идёт неправильно, чек-лист сигналов дизайна, которые стоит искать, и три скрипта для аудита усечений, подготовки брифов по дизайну и валидации черновиков.

Чтобы использовать его, укажите Claude на каталог навыка или скопируйте его в свой собственный .claude/skills/.

Безопасность

• Отсутствие сохранённых учётных данных. MCP-сервер не хранит пароли Acumatica. Он использует поток авторизации OAuth 2.0 — пользователи проходят аутентификацию напрямую в Acumatica.

• Персональные токены. Токен доступа Acumatica для каждого пользователя хранится в хранилище ключ-значение платформы (Cloudflare KV при развёртывании по умолчанию) и привязан к его имени пользователя. Токены автоматически обновляются по истечении срока действия. Если срок действия токена обновления истёк, соединение переаутентифицируется автоматически, без необходимости ручного переподключения.

• Шлюз доступа. Подключаться могут только те пользователи, которые могут читать назначенный канареечный Generic Inquiry. Сервер проверяет возможность чтения GI через OData во время входа (не по членству в ролях); пользователи без доступа видят страницу отказа в доступе. Вы можете ограничить GI любым способом — рекомендуется использовать роль-маркер MCP Access. Имя GI настраивается через ACUMATICA_CANARY_GI.

• Экран согласия. После прохождения проверки доступа пользователи должны подтвердить, что их данные будут обработаны внешней AI-моделью, прежде чем сессия MCP активируется.

• Редактирование конфиденциальных полей. Ответы инструментов автоматически сканируются на наличие имён конфиденциальных полей (SSN, банковские счета, зарплата, кредитные карты и т.д.), и найденные значения заменяются на [REDACTED]. Шаблоны настраиваются через переменные окружения REDACT_PATTERNS и REDACT_SKIP.

• Доступ на основе ролей. Роль пользователя в Acumatica определяет, какие записи он может читать. Если у пользователя нет доступа к записи в Acumatica, он не сможет получить к ней доступ и через MCP-сервер.

• Только чтение. Все текущие инструменты предназначены только для чтения. Никакие данные не создаются, не изменяются и не удаляются.

• Ограничение скорости. 3 одновременных запроса, 40 запросов в минуту и ограничение в 1000 записей на запрос по умолчанию — все параметры настраиваются из консоли администратора по адресу /docs/admin/settings без повторного развёртывания. Ограничения применяются к каждому пользователю и учитывают HTTP-вызовы к Acumatica (а не вызовы инструментов). Отклонения возвращают структурированный конверт с точным значением retryAfterSeconds и регистрируются как события rate_limit_hit, чтобы вы могли определить, не слишком ли жёсткие лимиты.

• Отказ от пагинации. Инструменты списка/запроса (acumatica_list_entities, acumatica_run_inquiry, acumatica_list_generic_inquiries) не поддерживают пагинацию. Когда ответ достигает ACUMATICA_MAX_RECORDS, инструмент возвращает структурированный конверт (truncated: true, paginationSupported: false, actionRequired: "..."), предписывающий AI остановиться и попросить пользователя указать более узкий фильтр, а не извлекать больше записей.

• Журнал аудита. Все вызовы инструментов, события аутентификации (успешный вход/отказ, принятие согласия) и события редактирования полей регистрируются в виде структурированного JSON. Просмотр с помощью npx wrangler tail.

Переносимость платформы

Хотя развёртывание по умолчанию нацелено на Cloudflare Workers, обработчики инструментов и основные библиотеки не зависят от платформы. Абстракция хранилища (интерфейс IKeyValueStore + тип AppEnv) отделяет логику инструментов от специфичных для Cloudflare API, что позволяет самостоятельно развёртывать сервер на Node.js с Redis, SQLite или другими бэкендами. Подробнее см. в Руководстве по самостоятельному развёртыванию.

Технологический стек

• Среда выполнения: Cloudflare Workers + Durable Objects

• MCP: agents SDK (McpAgent), @modelcontextprotocol/sdk

• Аутентификация: @cloudflare/workers-oauth-provider

• HTTP-маршрутизация: Hono

• Язык: TypeScript

• Валидация: Zod

Разработка

npx wrangler dev       # Start local dev server
npx tsc --noEmit       # Type check
npx wrangler tail      # Stream live logs from deployed worker

Лицензия

Apache 2.0 — Copyright 2026 Hall Boys, Inc.