Skip to main content
Glama
BOS MCP Server

BOS MCP Server

by bizino

BOS MCP Server

MCP (Model Context Protocol) server cho phép AI assistants (Claude, Cursor, Trae) tương tác trực tiếp với BOS ERP System qua REST API.

Tính năng

  • 69 tools cho business operations

  • TypeScript + Node.js 18+

  • Token bucket rate limiting (60 RPM)

  • Exponential backoff retry

  • Stdio & HTTP transport

  • JSON-RPC 2.0

Related MCP server: Conexa MCP

Cài đặt

npm install
npm run build

Environment Variables

Variable

Default

Mô tả

BOS_API_URL

https://bos.ai.vn

BOS domain root (NO /api suffix)

BOS_API_TOKEN

``

Bearer token cho auth (optional)

MCP_API_KEY

``

API key cho MCP M2M auth (required)

BOS_API_TIMEOUT

30000

Request timeout (ms)

Chạy

# Stdio mode (default - cho Claude Code)
npm start

# HTTP mode (cho web deployments)
npm run http

Claude Code Integration

{
  "mcpServers": {
    "bos": {
      "command": "node",
      "args": ["/path/to/bos-mcp/dist/index.js"],
      "env": {
        "BOS_API_URL": "https://bos.ai.vn/api"
      }
    }
  }
}

Docker

FROM node:18-alpine
WORKDIR /app
COPY package.json dist/
RUN npm install
CMD ["node", "dist/http.js"]

Tools Categories (69 total)

Health & Management (18 tools)

  • boscli_health_* - System health checks

  • boscli_module_* - Module CRUD

  • boscli_route_* - Route listing

  • boscli_cache_* - Cache management

  • boscli_system_* - System info, logs, git, deploy

Products (6 tools)

  • bos_product_list, bos_product_show, bos_product_search

  • bos_product_create, bos_product_update, bos_product_delete

Orders (6 tools)

  • bos_order_list, bos_order_show, bos_order_create

  • bos_order_update_status, bos_order_cancel, bos_order_count_by_status

Cart (7 tools)

  • bos_cart_get, bos_cart_add_item, bos_cart_update_item

  • bos_cart_remove_item, bos_cart_clear

  • bos_cart_apply_voucher, bos_cart_remove_voucher

Customers (5 tools)

  • bos_customer_list, bos_customer_show, bos_customer_create

  • bos_customer_update, bos_customer_orders

Inventory (4 tools)

  • bos_inventory_list, bos_inventory_check, bos_inventory_update

  • bos_inventory_low_stock

Vouchers (4 tools)

  • bos_voucher_list, bos_voucher_validate, bos_voucher_create

  • bos_customer_vouchers

Loyalty (5 tools)

  • bos_loyalty_points_balance, bos_loyalty_points_history

  • bos_loyalty_earn, bos_loyalty_redeem, bos_loyalty_tiers

Stores (3 tools)

  • bos_store_list, bos_store_show, bos_store_nearby

Checkout & Payment (4 tools)

  • bos_checkout_calculate, bos_checkout_create

  • bos_payment_methods, bos_payment_verify

Promotions (3 tools)

  • bos_promotion_list, bos_promotion_show, bos_promotion_apply

Home & Engagement (4 tools)

  • bos_home, bos_banners

  • bos_notifications, bos_notification_mark_read

License

MIT

Available Tools

108 tools
bos_accounting_summaryB

Get sales, purchases, expenses, and journal entry summary

Inputs: no named parameters.

bos_approval_listC

List approval requests/workflows when Approval module tables are installed

Inputs: page, page_size.

bos_bannersC

Get promotional banners

Inputs: location.

bos_business_infoB

Get business/shop settings and profile information

Inputs: no named parameters.

bos_cart_add_itemC

Add item to cart

Inputs: product_id (required), quantity (required), variant_id, notes.

bos_cart_apply_voucherC

Apply voucher code to cart

Inputs: voucher_code (required).

bos_cart_clearA

Clear all items from cart

Inputs: no named parameters.

bos_cart_getB

Get current user cart

Inputs: no named parameters.

bos_cart_remove_itemC

Remove item from cart

Inputs: item_id (required).

bos_cart_remove_voucherA

Remove voucher from cart

Inputs: no named parameters.

bos_cart_update_itemC

Update cart item quantity

Inputs: item_id (required), quantity (required).

bos_checkout_calculateC

Calculate checkout totals

Inputs: customer_id (required), shipping_address_id, voucher_code.

bos_checkout_createC

Create order from cart

Inputs: customer_id (required), shipping_address (required), payment_method (required), voucher_code.

boscli_cache_clearC

Clear BOS application caches

Inputs: type.

boscli_cache_listA

Get BOS cache configuration and status

Inputs: no named parameters.

boscli_health_cacheC

Check BOS cache systems

Inputs: no named parameters.

boscli_health_checkA

Full BOS system health check - modules, database, cache, routes

Inputs: no named parameters.

boscli_health_databaseA

Check BOS database connectivity

Inputs: no named parameters.

boscli_health_modulesB

Check health of all BOS modules

Inputs: no named parameters.

boscli_health_schemaB

Check BOS database schema integrity

Inputs: no named parameters.

boscli_module_disableB

Disable a BOS module by name

Inputs: module_name (required).

boscli_module_enableB

Enable a BOS module by name

Inputs: module_name (required).

boscli_module_listA

List all BOS modules with their enabled/disabled status

Inputs: no named parameters.

boscli_module_showB

Get details of a specific BOS module

Inputs: module_name (required).

boscli_route_by_moduleA

Get all routes for a specific BOS module

Inputs: module (required).

boscli_route_listC

List all BOS routes, optionally filtered by module

Inputs: module, limit.

boscli_system_deploy_statusC

Get deployment status for BOS servers

Inputs: customer.

boscli_system_git_statusA

Get BOS git repository status - branch, commit, changed files

Inputs: no named parameters.

boscli_system_infoA

Get BOS system information - version, PHP, Laravel, environment

Inputs: no named parameters.

boscli_system_logsC

Read recent BOS log entries

Inputs: lines, level.

bos_crm_lead_listC

List CRM leads from CRM module or contact fallback

Inputs: page, page_size.

bos_customer_address_createB

Add a new address for a customer

Inputs: customer_id (required), address_line_1 (required), city, state, +2 more.

bos_customer_address_deleteC

Delete a customer address

Inputs: customer_id (required), address_id (required).

bos_customer_address_listC

List all addresses for a customer

Inputs: customer_id (required).

bos_customer_address_updateD

Update a customer address

Inputs: customer_id (required), address_id (required), address_line_1, city, +1 more.

bos_customer_countC

Get total customer count with optional filters

Inputs: status.

bos_customer_createC

Create a new customer

Inputs: name (required), phone (required), email, address.

bos_customer_deleteC

Delete a customer

Inputs: customer_id (required).

bos_customer_listC

List customers with pagination

Inputs: page, page_size, search.

bos_customer_loyalty_summaryC

Get loyalty points summary for a customer

Inputs: customer_id (required).

bos_customer_ordersC

Get order history for a customer

Inputs: customer_id (required).

bos_customer_showC

Get customer details by ID

Inputs: customer_id (required).

bos_customer_transactionsC

Get payment transactions for a customer

Inputs: customer_id (required).

bos_customer_updateC

Update customer information

Inputs: customer_id (required), name, phone, email, +1 more.

bos_customer_vouchersC

Get vouchers for current customer

Inputs: status.

bos_delivery_shipment_listC

List delivery shipments or delivery orders when Delivery module tables are installed

Inputs: page, page_size.

bos_erp_overviewA

Get ERP overview counts for customers, suppliers, products, sales, purchases, and expenses

Inputs: no named parameters.

bos_expense_listC

List expense transactions and refunds

Inputs: page, page_size, from_date, to_date.

bos_homeA

Get home page data (banners, categories, featured products)

Inputs: no named parameters.

bos_hr_employee_listC

List ERP employees/users

Inputs: page, page_size.

bos_integration_statusA

Get connection counts for ERP integration modules such as KiotViet, Sapo, EcomSync, Marketplace, and AMIS

Inputs: no named parameters.

bos_inventory_checkC

Check stock quantity for a product

Inputs: product_id (required).

bos_inventory_listC

List inventory stock across all products

Inputs: page, page_size, warehouse_id.

bos_inventory_low_stockC

Get products with low stock alerts

Inputs: threshold.

bos_inventory_updateC

Update inventory stock

Inputs: product_id (required), quantity (required), type (required), reason.

bos_loyalty_earnD

Earn loyalty points

Inputs: customer_id (required), points (required), order_id, description.

bos_loyalty_points_balanceC

Get loyalty points balance for customer

Inputs: customer_id (required).

bos_loyalty_points_historyC

Get loyalty points transaction history

Inputs: customer_id (required), page, page_size.

bos_loyalty_redeemC

Redeem loyalty points

Inputs: customer_id (required), points (required), reward_id.

bos_loyalty_tiersB

Get loyalty tier information

Inputs: no named parameters.

bos_notification_mark_readB

Mark notification as read

Inputs: notification_id (required).

bos_notificationsC

Get user notifications

Inputs: page, unread_only.

bos_order_add_noteC

Add a staff note to an order

Inputs: order_id (required), note (required).

bos_order_cancelC

Cancel an order

Inputs: order_id (required), reason.

bos_order_count_by_statusB

Get order counts grouped by status

Inputs: no named parameters.

bos_order_createC

Create a new order

Inputs: customer_id (required), items (required), shipping_address, payment_method, +1 more.

bos_order_listC

List orders with filters

Inputs: page, page_size, status, from_date, +1 more.

bos_order_refundC

Process a refund for an order

Inputs: order_id (required), amount, reason.

bos_order_shipping_infoC

Get shipping information for an order

Inputs: order_id (required).

bos_order_showB

Get order details by ID

Inputs: order_id (required).

bos_order_transactionsC

Get payment transactions for an order

Inputs: order_id (required).

bos_order_update_shippingC

Update shipping status for an order

Inputs: order_id (required), shipping_status (required), tracking_number.

bos_order_update_statusC

Update order status

Inputs: order_id (required), status (required).

bos_payment_methodsC

Get available payment methods

Inputs: no named parameters.

bos_payment_verifyC

Verify payment status

Inputs: order_id (required).

bos_product_categoriesA

Get all product categories

Inputs: no named parameters.

bos_product_countB

Get total product count with optional filters

Inputs: status.

bos_product_createC

Create a new product

Inputs: name (required), price (required), sku, category_id, +2 more.

bos_product_deleteC

Delete a product

Inputs: product_id (required).

bos_product_imagesD

Get images for a product

Inputs: product_id (required).

bos_product_listC

List products with pagination and filters

Inputs: page, page_size, category_id, search, +1 more.

bos_product_showA

Get product details by ID

Inputs: product_id (required).

bos_product_stockB

Get stock levels for a product across all locations

Inputs: product_id (required).

bos_product_updateC

Update an existing product

Inputs: product_id (required), name, price, stock, +1 more.

bos_product_variantsC

Get all variants for a product

Inputs: product_id (required).

bos_promotion_applyC

Apply promotion to order

Inputs: promotion_id (required), order_id (required).

bos_promotion_listC

List active promotions and campaigns

Inputs: page, page_size.

bos_promotion_showC

Get promotion details

Inputs: promotion_id (required).

bos_purchase_listC

List purchase transactions and purchase orders

Inputs: page, page_size, from_date, to_date.

bos_smart_customer_segmentsA

Phân tích RFM (Recency, Frequency, Monetary) chia khách hàng thành 8 tập (segments) kèm gợi ý hành động marketing.

Inputs: no named parameters.

bos_smart_inventory_healthC

Phân loại tình trạng kho hàng: out_of_stock, low, dead (tồn kho khó bán), healthy.

Inputs: store_id (required).

bos_smart_inventory_imbalanceB

Phát hiện sự mất cân bằng tồn kho giữa các chi nhánh và đề xuất chuyển kho nội bộ.

Inputs: no named parameters.

bos_smart_order_cycle_timeB

Phân tích thời gian xử lý đơn hàng (từ lúc tạo đến xác nhận, đóng gói, giao hàng) để tìm ra điểm nghẽn.

Inputs: start_date (required), end_date (required).

bos_smart_orders_summaryC

Tổng hợp doanh thu, AOV, phân bổ trạng thái/nguồn/lý do huỷ, và so sánh với kỳ trước. Rất hữu ích cho báo cáo tổng quan.

Inputs: start_date (required), end_date (required), compare_previous (required).

bos_smart_stock_reorder_planB

Dự báo tốc độ bán hàng (DSR), điểm đặt hàng lại (reorder point) và số lượng đề xuất nhập cho từng sản phẩm.

Inputs: store_id (required), days_to_cover (required).

bos_smart_top_productsA

Lấy top N sản phẩm theo doanh thu, số lượng bán, bao gồm chi tiết hiệu suất từng phân loại (variant).

Inputs: limit (required), sort_by (required), start_date (required), end_date (required).

bos_stock_movement_listC

List stock adjustments, transfers, and opening stock movements

Inputs: page, page_size, from_date, to_date.

bos_store_inventoryC

Get inventory summary for a specific store

Inputs: store_id (required).

bos_store_listB

List all stores locations

Inputs: no named parameters.

bos_store_nearbyC

Find nearby stores by location

Inputs: latitude (required), longitude (required), radius.

bos_store_showC

Get store details

Inputs: store_id (required).

bos_store_staffC

Get staff members for a store

Inputs: store_id (required).

bos_voucher_createD

Create a new voucher

Inputs: code (required), type (required), value (required), start_date (required), +4 more.

bos_voucher_listC

List available vouchers

Inputs: page, page_size, status.

bos_voucher_validateC

Validate a voucher code

Inputs: code (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 108 tools

    Disambiguation3/5

    While each tool has a clear description, the high number (108) and overlapping domains (e.g., multiple list and search tools) create potential confusion. Agents might struggle to select the correct tool among many similar ones, especially with mixed language descriptions.

    Naming Consistency5/5

    All tools follow a consistent 'bos_<domain>_<action>' pattern in snake_case. Verbs are predictable (list, create, update, delete, get, search, show), making navigation easy despite the large set.

    Tool Count2/5

    108 tools is far too many for a single MCP server. It attempts to cover an entire retail/ERP system, including CLI commands, smart analytics, and administrative functions. The tool surface should be split into multiple focused servers (e.g., orders, products, customers, admin).

    Completeness4/5

    The tools cover the core lifecycle for most domains: customers (CRUD + addresses), products (CRUD + variants), orders (full workflow), cart/checkout, inventory, and more. Minor gaps exist (e.g., no category management beyond listing), but overall it's comprehensive for a retail system.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server integrating with Odoo ERP systems, enabling AI assistants to interact with Odoo data and functionality through tools and resources.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server that connects AI assistants to the Conexa business management system, enabling CRUD operations on sales, customers, plans, contracts, charges, and more via 83 tools.
      83
      121 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query ERP sales data, including employees, sales, customers, and top products, through MCP tools.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server that enables AI platforms to search products, customers, and warehouses, and prepare and submit sales orders to a fixed ERP endpoint with per-session bearer authentication.
      -