MCP4Acumatica

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

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

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

Возможности

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

• OAuth для каждого пользователя — пользователи входят со своими учётными данными Acumatica (или через SSO)

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

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

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

• Маскирование чувствительных полей — SSN, банковские счета, зарплата и другие поля с персональными данными автоматически вымываются до того, как данные покинут сервер

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

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

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

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

• Долгосрочное хранение логов — журналы сохраняются в R2 через Cloudflare Logpush, с поиском и просмотром в веб-интерфейсе

Архитектура

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 (области (scopes) передаются сервером в запросе, а не настраиваются в приложении)

  • Есть redirect URI, указывающий на конечную точку /callback вашего worker'а

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

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

Установка

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

Путь А — кнопка Deploy to Cloudflare (без терминала)

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

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

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

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

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

3. Задайте секреты. В полученные запросы вставьте:

   • ACUMATICA_CLIENT_ID — из вашего Connected Application (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. Обновите переменные Acumatical. Когда развертывание завершится, перейдите в Workers & Pages → mcp4acumatica → Settings → Variables and Secrets в панели управления Cloudflare и измените:

   • ACAMATICA_URL — например, https://yourcompany.acumatica.com

   • ACUMATICA_TENANT — ваша рабочая компания

   • Необязательно: ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP

   Нажмите Save and Deploy — Cloudflare переразвернёт с новыми значениями.

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

7. Проверьте развертывание. Откройте https://<your-host>/docs/admin/preflight, войдите с помощью вашего ADMIN_SECRET, запустите диагностику preflight. Она проверяет подключение к Acumatica, endpoint Odiscovery, учётные данные Connected App, путь tenant'а и версию контрактного API, присваивая каждой неверной настройке имя.

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

Путь Б — установка одной командой (терминал)

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

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

Эта команда клонирует репозитоистой, установит зависимости и запустит ./setup.sh. Скрипт запросит требующиеся значения Acumatica (URL, tenant, Client ID, Client Secret), автоматически создаст криптографические секреты, создат namespace KV и корзину R2, загрузит секреты, развернёт приложение и затем запустит проверку preflight.

Если вы хотите сначала посмотреть скрипт:

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

Вариант — ручная установка (терминал)

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

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

2. Создание namespace KV

npx wrangler kv namespace create TOKEN_STORE

Из результата выберите namespace ID — на следующем шаге он вам понадобится для wrangler.jsonc. Один и особенность этот ID используется для обоих TOKEN_STORE и OAUTH_KV-binding'ов.

3. Конфигурация wrangler

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

• namespace ID из шага 2 (для обоих TOKEN_STORE и OAUTH_KV — один и тот же id)

• ACUMATICA_URL — URL вашего экземпляра Acumenrica.com

• ACUMATICA_TENANT — имя вашей компании в Acumatica

Чтобы не портить рабочую копию и продолжать получать обновления без конфликтов:

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 (SSM303010).

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

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

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

5. Обратите внимание на Client ID и Client Secret — при развертывании они станут секретами.

Здесь не настраивается fields scopes. OAuth-области (api openid profile email offline_access, в том числе offline_access, благодаря которому Acumatica выдаёт refresh-токены) отправляет сам MCP-сервер в запросе авторизации — в консоли Connected Application их не указывают.

Шлюз доступа: контрольный Generic Inquiry (SM208000, SM201005)

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

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

2. Ограничьте доступ к его чтению (рекомендуется роль-маркер): Система > Права доступа > Роли пользователей (SM201000) → создайте роль MCP Access без прав на экраны, выдайте ей только MCPAccess GI, после этого назначьте рольтемпользователям, кому нужен ассистент ИИ. Подойдут и любые над мышле другой механизм ограничения OData-доступа к GI.

Имя контрольного GI настраивается через ACUMATICA_CANARY_GI (по умолчанию MCPAccess). Изменить её можно на появление чандадрический «переменные переменные», измер. в wrangler.jsonc.

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

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

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

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

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

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

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

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

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

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

Claude.ai / Claude Desktop

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

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

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

4. Если на вашей учётной записи есть доступ к канареечному GI (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 и Payroll

Активности CRM

Утилиты / Поиск

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

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

Подробную документацию можно найти в папке docs/:

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

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

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

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

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

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

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

• Обновление Ac القيت -- шаги при изменении или обновлении подключённой версии Acumatica

Навыки

Многократно используемые навыки Claude, которые входят в репозиторий, находятся в папке skills/:

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

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

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

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

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

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

• Промежуточная страница согласия. После прохождения проверки доступа пользователи должны подтвердить, что их данные будут обработаны внешней ИИ-моделью, прежде чем активируется 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: \"...\"), которая предписывает ИИ остановиться и попросить пользователя задать более узкий фильтр, а не запрашивать дальнейшие записи.

• Журналирование аудита. Все вызовы инструментов, события аутентификации (успешная авторизация, отказ во входе, принятие согласия) и события маскирования полей регистрируются как структурированный 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.