@ohlom/biz-mcp — Ohlom Business MCP server

An MCP server that lets a business owner manage their Ohlom business pages conversationally from Claude (or any MCP client) over the partner API (/api/v1/*) — read the catalog, sync inventory, work orders, check the HR attendance board, send official customer messages, manage webhooks, and publish posts with media.

It talks to the same partner API a POS or ERP integration uses, with the same OAuth scopes the owner granted, so it can do exactly what the approved integration may do — no more.

What it exposes

| Area | Tools | |------|-------| | Identity | biz_whoami | | Catalog | biz_list, biz_products, biz_inventory_update | | Orders | biz_orders, biz_order_update | | HR attendance | biz_attendance_today, biz_attendance_staff, biz_attendance_report | | Official messaging | biz_message_send, biz_message_status | | Webhooks | biz_webhooks (list / create / delete) | | Content | biz_post_create, biz_media_upload (publishes as the page — see notes) |

All money values (order totals, product prices) are in Kip.

Getting credentials

1. Create a developer app on dev.ohlom.com (a confidential app — public/PKCE-only apps cannot use client_credentials). Request the scopes you need, e.g. catalog:read orders:read orders:write inventory:write attendance:read messages:send.
2. The business owner approves the app for their business in the biz portal (biz.ohlom.com) under API settings. The approval pins which scopes the app actually gets for that business.
3. You now have a client_id + client_secret (from the developer app) and the business id (shown in the biz portal next to the approval). That's everything this server needs.

Setup

cd sdks/ohlom-biz-mcp
npm install
npm run build

Environment

OHLOM_BIZ_CLIENT_ID=oa_...            # developer app client id
OHLOM_BIZ_CLIENT_SECRET=•••••••       # developer app client secret
OHLOM_BIZ_BUSINESS_ID=<uuid>          # the business that approved the app
OHLOM_BIZ_SCOPES=...                  # optional; defaults to
                                      #   catalog:read orders:read orders:write
                                      #   inventory:write attendance:read
                                      #   messages:send media:write posts:write
                                      # (narrowed to what the owner granted)
OHLOM_API_BASE=https://api.ohlom.com  # optional; set http://localhost:8080 for dev

The server logs in with OAuth2 client_credentials against POST {OHLOM_API_BASE}/oauth/token, caches the access token in memory, refreshes it 60 seconds before expiry, and retries once on a 401 — so it just keeps working without re-pasting tokens.

Register with Claude Code

Add to your project .mcp.json (or run claude mcp add):

{
  "mcpServers": {
    "ohlom-biz": {
      "command": "node",
      "args": ["sdks/ohlom-biz-mcp/dist/index.js"],
      "env": {
        "OHLOM_API_BASE": "https://api.ohlom.com",
        "OHLOM_BIZ_CLIENT_ID": "your-client-id",
        "OHLOM_BIZ_CLIENT_SECRET": "your-client-secret",
        "OHLOM_BIZ_BUSINESS_ID": "your-business-uuid"
      }
    }
  }
}

Register with Claude Desktop

claude_desktop_config.json → mcpServers (same shape; use an absolute path to dist/index.js).

Notes & limits

• Posting as the page. With app (client_credentials) credentials, biz_post_create / biz_media_upload act as the authorized business's owner and are pinned server-side to publishing AS that page (public, non-community) — the app can never make a personal post or touch another page. Requires the posts:write + media:write scopes on the approval.
• Official messages need a verified business and an approved template; free-form text is rejected in the current phase. Sends are idempotent per idempotency_key and capped per recipient per day.
• Order status values: 0 pending, 1 confirmed, 2 preparing, 3 shipped, 4 delivered, 5 cancelled — the server rejects illegal transitions.
• Inventory: stock: null marks the product untracked/unlimited; omitting a field leaves it unchanged.
• The webhook signing secret is returned exactly once on create — store it and verify X-Ohlom-Signature with it.
• Treat the client secret as production access to the business. Keep it out of shared configs and version control.