Skip to main content
Glama

Luceed MCP

Read-only Model Context Protocol bridge to Tomsoft Luceed ERP web services (datasnap/rest).

Connect Claude, ChatGPT, Cursor, or any MCP client and ask things like “How much retail sales did we have last week?”

Coverage: 39 resources / 149 GET actions from Luceed Web Services 2.206. Write APIs (*/snimi, status mutations, etc.) are intentionally excluded.

Built by Debug Labs

Maintained by Debug Labs d.o.o. — a Croatia-based software company specializing in Luceed ERP integrations, Magento / e‑commerce sync, and custom B2B automation around Tomsoft Luceed.

If you need help wiring Luceed to your webshop, marketplace, BI tools, or AI assistants (this MCP included), get in touch:

This open-source MCP adapter is independent of Tomsoft. Luceed® is a product of Tomsoft d.o.o.

Related MCP server: Odoo MCP Improved

Official Luceed API docs

Luceed exposes a RESTful JSON API with HTTP Basic authentication. Access is granted per customer — contact the Luceed instance owner for credentials and allowed methods.

This MCP maps the documented GET surface into discoverable tools (luceed_catalog). Official field-level docs stay with Tomsoft and are not redistributed here.

Architecture

Claude / ChatGPT / Cursor
        │  HTTPS + OAuth (ChatGPT/Claude) or Bearer (Cursor/curl)
        ▼
   TLS reverse proxy (Apache / nginx)
        │  /mcp-<secret> + OAuth routes → 127.0.0.1:8080
        ▼
   Docker (user: luceed-mcp)  ← .env in ~/Luceed-mcp
        │  optional auto SSH tunnel (bastion private IP → Luceed)
        ▼
   Luceed datasnap/rest  (HTTP Basic, GET only)

Deploy + proxy + CDN + SSH tunnel: docs/DEPLOY.md
Connect ChatGPT (OAuth / Streamable HTTP), Claude, Cursor: docs/CONNECT.md

Docker image (GHCR)

Every push to main publishes:

ghcr.io/splacento-incomm/luceed-mcp:latest
docker pull ghcr.io/splacento-incomm/luceed-mcp:latest

Production deploy (ChatGPT / Claude)

  1. Dedicated OS user luceed-mcp + Docker on 127.0.0.1:8080

  2. .env with MCP_HTTP_PATH, MCP_AUTH_TOKEN, and OAuth (MCP_PUBLIC_URL, MCP_OAUTH_PASSWORD, MCP_OAUTH_SECRET)

  3. Apache/nginx TLS proxy for the MCP path and OAuth routes (/.well-known/*, /authorize, /token, /register, /oauth/)

  4. Avoid Cloudflare browser challenges on those paths (or use a DNS-only hostname)

  5. Optional: SSH_ENABLED=true — SSH_HOST = bastion the MCP host can reach (often private IP); SSH_REMOTE_HOST = Luceed as seen from that bastion

Full steps + troubleshooting: docs/DEPLOY.md
Client setup: docs/CONNECT.md

Install as a Codex plugin

For Codex Desktop, use the bundled installer instead of manually adding an MCP server in Settings. It creates a real Luceed plugin entry, with your deployment URL stored only in your local plugin configuration:

npm run install:codex-plugin -- --url https://mcp.example.com/mcp-your-secret

If your deployment requires the optional Bearer token, configure it in your desktop environment first, then tell the installer which environment variable to use:

export LUCEED_MCP_AUTH_TOKEN='your-token'
npm run install:codex-plugin -- \
  --url https://mcp.example.com/mcp-your-secret \
  --token-env LUCEED_MCP_AUTH_TOKEN

Restart Codex, open Plugins → Browse directory → Personal, install Luceed, and start a new task. Full details are in docs/CODEX.md.

Quick start (local / stdio)

git clone https://github.com/splacento-incomm/Luceed-mcp.git
cd Luceed-mcp
cp .env.example .env   # set LUCEED_* credentials
npm install && npm run build
npm run start:stdio

Cursor / Claude Desktop

{
  "mcpServers": {
    "luceed": {
      "command": "node",
      "args": ["/absolute/path/to/Luceed-mcp/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "LUCEED_BASE_URL": "http://127.0.0.1:18080/datasnap/rest/",
        "LUCEED_USERNAME": "readonly_user",
        "LUCEED_PASSWORD": "secret"
      }
    }
  }
}

Tools

Tool

Role

luceed_catalog

List all resources/actions/paths

luceed_ping

Auth / connectivity check

luceed_<resource>

One tool per resource; pass action + params

luceed_recent_sales_orders

Preferred for “last N sales orders” (sorted newest-first)

luceed_retail_sales_summary

Sales totals by payment type

luceed_retail_sales_by_product

Sales by product

luceed_get

Raw relative GET escape hatch

Ask the model to call luceed_catalog first.

Resources

artikli, artikli_popusti, bundle, skladista, stanje_zalihe, stanje_zalihe_dobavljaci, stanje_zalihe_serijski, cijene, cjenik, cjenik_partner, akcije, prodajne_akcije, prodajni_uvjeti, partneri, users, mjesta, vrste_placanja, grupe_artikala, robne_marke, sifrarnici, statusi, prijevodi, varijante, bodovi, tecajna_lista, crm_razlozi, predmeti, mpracuni, mpobracun, nalozi_prodaje, vpracuni, racuni_predujma, narudzbe, nalozi_povrata, nalozi_proizvodnje, radni_nalozi, skladisni_dokumenti, hotel, poklon_bonovi

Config

Variable

Required

Notes

LUCEED_BASE_URL

yes

Must include /datasnap/rest/

LUCEED_USERNAME / LUCEED_PASSWORD

yes

HTTP Basic

MCP_TRANSPORT

stdio or http

MCP_AUTH_TOKEN

for HTTP

Bearer / X-API-Key

MCP_HTTP_PATH

Unguessable path e.g. /mcp-a8f3…

LUCEED_MCP_IMAGE

Override GHCR image tag

SSH_ENABLED

Local forward for IP-whitelisted Luceed

See .env.example, docs/SETUP.md, docs/DEPLOY.md.

Need a Luceed integration?

Debug Labs builds production Luceed connectors for e‑commerce, logistics, and reporting — Magento product/stock/order sync, B2B portals, and AI tooling like this MCP.

debug-labs.hr · open an issue on this repo for MCP-specific questions.

License

MIT — © Debug Labs d.o.o. / contributors

Luceed® / Tomsoft® names are trademarks of their respective owners. Official web-service documentation remains Tomsoft’s intellectual property and is not redistributed in this repository. See docs.tomsoft.hr/luceedapi.

Available Tools

45 tools
luceed_akcijeC

Sales campaigns 1.0: Promotional campaigns (akcije). Actions: lista.

Inputs: action (required).

luceed_artikliC

Products (artikli): Product catalog: by code, barcode, UID, name, group, brand, attribute, list. Actions: sifra, sifradio, barcode, uid, naziv, lista, grupa, grupa_naziv, robna_marka, robna_marka_naziv, atribut, dokumenti, dodaci, prijevodi, sastavnice_sifra, sastavnice_uid.

Inputs: action (required), tip, uid, page, +8 more.

luceed_artikli_popustiC

Items on sale / discounts: Articles currently on sale (artiklipopusti). Actions: lista, sifra.

Inputs: action (required), sifra.

luceed_bodoviC

Scoring / points: Loyalty scoring system data. Actions: lista.

Inputs: action (required), od_datuma.

luceed_bundleC

Bundle items: Bundle article definitions and components. Actions: lista, lista_uid, lista_b2b.

Inputs: action (required), b2b, uid.

luceed_catalogB

List all mapped Luceed read-only resources/actions/paths. Filter with resource id or magento_only=true for endpoints used by Magento Debuglabs/Luceed.

Inputs: resource, magento_only.

luceed_cijeneB

Current prices: Current selling price including promotions. Actions: sifra, barcode, partner, loyalty.

Inputs: action (required), sifra, valuta, barcode, +3 more.

luceed_cjenikC

Price list: Service partner price list. Actions: lista.

Inputs: action (required).

luceed_cjenik_partnerC

Partner price list: Partner-specific price lists and diffs. Actions: sifra, uid, getdiff.

Inputs: action (required), tip, uid, page, +3 more.

luceed_crm_razloziC

CRM visit causes: CRM visit reason codes. Actions: lista.

Inputs: action (required).

luceed_getA

Raw read-only GET for any relative datasnap/rest path not covered (or for ad-hoc exploration). Mutating paths blocked when LUCEED_READ_ONLY=true. Prefer catalog tools when possible. Example: artikli/sifra/111

Inputs: path (required).

luceed_grupe_artikalaC

Product groups: Article groups. Actions: lista, sifra, naziv, dodaci.

Inputs: action (required), sifra, dio_naziva.

luceed_hotelC

Hotel: Hotel reservations, registrations, guest overview. Actions: rezervacije_lista, rezervacije_uid, prijave, lista, gosti.

Inputs: action (required), uid, datum, voucher, +6 more.

luceed_mjestaC

Locations / cities: Places (mjesta) — Magento uses mjesta/list for full list. Actions: list, sifra, naziv, postanskibroj.

Inputs: action (required), sifra, dio_naziva, postanski_broj.

luceed_mpobracunB

Retail sales calculations: Retail turnover by payment type or by product — use for 'how much sales'. Actions: placanja, artikli.

Inputs: action (required), pj_uid, do_datuma, od_datuma.

luceed_mpracuniC

Retail invoices: Maloprodajni računi — list and fetch retail invoices. Actions: lista, uid, broj, nalogprodaje, barcode, pdf.

Inputs: action (required), uid, broj, godina, +4 more.

luceed_nalozi_povrataC

Return orders: Return orders (NaloziPovrata). Actions: uid, b2b, izmjena_status, zaprimljene_kolicine.

Inputs: action (required), b2b, uid, timestamp.

luceed_nalozi_prodajeA

Sales orders (nalozi prodaje): B2B / wholesale sales orders — heavily used by Magento sync. IMPORTANT: Luceed does NOT sort or paginate. For 'latest N orders' prefer tool luceed_recent_sales_orders (it sorts by date/number). Raw statusi results are unsorted and require a status filter. Actions: statusi, partner, izmjena_status, uid, b2b, dokumenti, placanja_predujmom, dokumenti_isporuke_uid, dokumenti_isporuke_b2b, prijevoznica_pdf.

Inputs: action (required), b2b, uid, partner, +5 more.

luceed_nalozi_proizvodnjeC

Production orders: Production orders (NaloziProizvodnje). Actions: uid, statusi, partner, izmjena_status, dokumenti_isporuke_uid, dokumenti_isporuke_b2b.

Inputs: action (required), b2b, uid, partner, +4 more.

luceed_narudzbeC

Purchase orders (narudžbe): Purchase orders — retrieve and status changes. Actions: statusi, partner, partner_statusi, izmjena_status, uid, broj, zaprimljene_kolicine.

Inputs: action (required), uid, broj, godina, +6 more.

luceed_partneriC

Partners / customers: Partner master data lookup. Actions: sifra, oib, naziv, prezime, email, uid, gln, grupa, nivo, korisnici.

Inputs: action (required), gln, oib, uid, +8 more.

luceed_pingA

Health check: verify Luceed credentials/connectivity via skladista/lista.

Inputs: no named parameters.

luceed_poklon_bonoviC

Gift vouchers: Gift voucher validity / balance. Actions: stanje.

Inputs: action (required), serijski.

luceed_predmetiC

Cases (predmeti): CRM / case records. Actions: lista, sifra, uid.

Inputs: action (required), uid, sifra.

luceed_prijevodiC

Translations: Translation records for tables. Actions: lista.

Inputs: action (required), uid, jezik, tablica.

luceed_prodajne_akcijeC

Sales campaigns 2.0: Sales campaigns v2 (prodajneakcije). Actions: lista.

Inputs: action (required).

luceed_prodajni_uvjetiD

Sales conditions: Sales conditions for partners. Actions: partneri.

Inputs: action (required), partneri.

luceed_racuni_predujmaD

Advance payment invoices: Računi predujma. Actions: uid, b2b, pdf.

Inputs: action (required), b2b, uid.

luceed_radni_naloziC

Work / service orders: Radni nalozi (service work orders). Actions: uid, webkod, partner, partner_uid, stavke.

Inputs: action (required), b2b, uid, webkod, +4 more.

luceed_recent_sales_ordersA

PREFERRED for 'last N sales orders / nalozi prodaje'. Fetches NaloziProdaje by status + date window, dedupes, sorts newest-first (datum then broj), and returns only limit rows. Do NOT use raw luceed_nalozi_prodaje statusi for this — Luceed returns unsorted batches and a single status can miss other recent orders.

Inputs: days, limit, to_date, statuses, +1 more.

luceed_retail_sales_by_productC

Convenience: retail sales by product (wraps mpobracun/artikli).

Inputs: pj_uid (required), from_date (required), to_date.

luceed_retail_sales_summaryA

Convenience: retail sales totals by payment type for a PJ + date range (wraps mpobracun/placanja). Prefer this for 'how much sales'.

Inputs: pj_uid (required), from_date (required), to_date.

luceed_robne_markeC

Brands: Brand / robne marke list. Actions: lista.

Inputs: action (required).

luceed_sifrarniciC

Code lists: Generic Luceed code lists (countries, etc.). Magento uses drzava. Actions: list, list_one, fulllist, info, naziv, sifra, uid.

Inputs: action (required), value, sifrarnik.

luceed_skladisni_dokumentiC

Warehouse documents: Skladišni dokumenti. Actions: uid, barcode.

Inputs: action (required), uid, barcode.

luceed_skladistaC

Warehouses: Warehouse and business unit master data. Actions: lista, sifra.

Inputs: action (required), sifra.

luceed_stanje_zaliheC

Stock status: Stock and availability by warehouse / article / barcode / attribute. Actions: skladiste, skladiste_artikl, vrsta_skladista, vrsta_skladista_artikl, artikl, barcode, artikl_uid, atribut.

Inputs: action (required), tip, uid, vrste, +5 more.

luceed_stanje_zalihe_dobavljaciC

Supplier stock: Supplier stock levels (StanjeZaliheDobavljaci). Actions: lista, artikl, dobavljac, artikl_dobavljac.

Inputs: action (required), sifra, sifra_artikla, sifra_dobavljaca.

luceed_stanje_zalihe_serijskiC

Serial-number stock: Stock status by serial number. Actions: artikl, serijski.

Inputs: action (required), sifra, serijski.

luceed_statusiC

Statuses: Status definitions by domain. Actions: lista, domena, nalozi_prodaje.

Inputs: action (required), domena.

luceed_tecajna_listaC

Exchange rates: Currency exchange rate list. Actions: lista.

Inputs: action (required).

luceed_usersC

Users: Loyalty / web users (read). Actions: listatip, listaprezime, listaime, uid, username.

Inputs: action (required), tip, uid, username, +2 more.

luceed_varijanteC

Variants: Product variants. Actions: lista.

Inputs: action (required).

luceed_vpracuniC

Wholesale invoices: VP računi — wholesale invoices. Actions: uid, broj, nalogprodaje, lista_period, lista_partner, lista_skladiste, pdf.

Inputs: action (required), uid, broj, godina, +5 more.

luceed_vrste_placanjaC

Payment types: Payment type master data. Actions: list.

Inputs: action (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 45 tools

    Disambiguation3/5

    Several tools share overlapping domains, such as sales campaigns v1 vs v2, retail sales wrappers vs raw mpobracun, stock status variants (regular, supplier, serial), and multiple order types, which can cause misselection. However, descriptions often clarify use cases and explicitly state preferences (e.g., 'PREFERRED for last N sales orders'), mitigating some confusion.

    Naming Consistency4/5

    All tools use a consistent luceed_ prefix and snake_case, making names predictable. However, the set mixes resource-name tools (luceed_artikli, luceed_partneri) with convenience/action tools (luceed_retail_sales_summary, luceed_recent_sales_orders, luceed_get) rather than a uniform verb_noun pattern.

    Tool Count2/5

    With 45 tools, the set is heavy for an agent to manage, and several tools could be consolidated (sales campaign versions, retail sales wrappers, stock status variants). While the ERP domain is broad, the volume risks overwhelming agents and increases selection difficulty.

    Completeness4/5

    For a read-only ERP integration, the surface covers most major resources (products, stock, prices, partners, orders, invoices, CRM, hotel) and includes luceed_get and luceed_catalog for ad-hoc gaps. Write operations are largely absent, but this appears intentional for the read-only scope.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides AI agents with read-only access to Rossum API resources (queues, schemas, hooks, workspaces) for analysis purposes.
      6
      2
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A comprehensive implementation of the Model Context Protocol for Odoo ERP systems that enables AI assistants to interact directly with business data across sales, purchases, inventory, and accounting modules.
      49
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A read-only MCP server for SimpleShop accounting data, enabling AI agents to find documents, download PDFs, inspect products, and review sales exports.
      5
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides structured access to Dolibarr ERP/CRM API endpoints via the Model Context Protocol, supporting CRUD operations on resources like thirdparties, products, and orders.
      1
      MIT