Content
# logiwa-mcp-server
An [MCP](https://modelcontextprotocol.io) server for the **Logiwa IO (WMS)** API. It lets MCP clients
(Claude Desktop, Claude Code, etc.) work with your Logiwa warehouse data through well-described tools:
products, inventory, shipment/purchase/return orders, warehouses & locations, customers/vendors/retailers,
key reports, and reference lookups.
- **Language / transport:** TypeScript · stdio
- **API base:** `https://myapi.logiwa.com` (override with `LOGIWA_BASE_URL`)
- **Auth:** JWT bearer — fetched from email/password, or a pre-issued token
- **Tools:** 32 (see [Tools](#tools))
Built with the [`mcp-builder`](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) skill.
---
## Prerequisites
- **Node.js ≥ 18**
- A **Logiwa IO account.** Each user authenticates with their own credentials (email/password or a pre-issued JWT). The server calls the Logiwa API on behalf of whoever's credentials are configured — **no credentials are bundled in this repo**, so every user must supply their own.
## Setup
```bash
git clone https://github.com/cgtykctn/Logiwa-IO-WMS--MCP-.git
cd Logiwa-IO-WMS--MCP-
npm install
npm run build
```
Then verify the build without needing credentials:
```bash
node dist/index.js --list-tools # prints the 32 registered tools
```
## Authentication
The server authenticates with a JWT bearer token. Provide credentials via environment variables
(see [`.env.example`](./.env.example)):
| Variable | Description |
|---|---|
| `LOGIWA_EMAIL` + `LOGIWA_PASSWORD` | **Recommended.** The server `POST`s these to `/v3.1/Authorize/token`, caches the returned JWT in memory, and re-authenticates automatically on a 401. |
| `LOGIWA_API_TOKEN` | A pre-issued JWT. If set, it takes precedence and no login call is made. |
| `LOGIWA_BASE_URL` | Optional. API base URL (default `https://myapi.logiwa.com`). |
| `LOGIWA_TIMEOUT_MS` | Optional. Per-request timeout in ms (default `30000`). |
Credentials are read from the process environment only — nothing is written to disk or logged.
## Register with an MCP client
> Replace `/absolute/path/to/Logiwa-IO-WMS--MCP-` with the real path where you cloned the repo, and use **your own** Logiwa email/password. The server runs locally (stdio) alongside your MCP client — each user installs and configures it on their own machine.
### Claude Code (CLI)
```bash
claude mcp add logiwa \
--env LOGIWA_EMAIL=you@example.com \
--env LOGIWA_PASSWORD=your-password \
-- node "/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"
```
### Claude Desktop
Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"logiwa": {
"command": "node",
"args": ["/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"],
"env": {
"LOGIWA_EMAIL": "you@example.com",
"LOGIWA_PASSWORD": "your-password"
}
}
}
}
```
Restart the client after editing. Tools then appear under the `logiwa` server.
## Tools
All list/report tools paginate with `page` (1-based) and `page_size` (≤200), and accept
`response_format` (`markdown` default, or `json` for full structured data). Logiwa's list endpoints
paginate by page index only (no server-side text filter), so page through results or use a `get`/`lookup`
tool when you already know an identifier. Write tools expose the API's required fields plus an
`additional_fields` escape hatch for any other Logiwa body field.
**Products** — `logiwa_list_products`, `logiwa_get_product`, `logiwa_create_product`, `logiwa_update_product`
**Inventory** — `logiwa_list_inventory`, `logiwa_add_inventory`, `logiwa_adjust_inventory`, `logiwa_remove_inventory`, `logiwa_transfer_inventory`
**Shipment orders** — `logiwa_list_shipment_orders`, `logiwa_get_shipment_order`, `logiwa_create_shipment_order`, `logiwa_update_shipment_order`, `logiwa_cancel_shipment_order`, `logiwa_ship_shipment_orders`
**Purchase orders** — `logiwa_list_purchase_orders`, `logiwa_get_purchase_order`, `logiwa_create_purchase_order`, `logiwa_receive_purchase_order`
**Return orders** — `logiwa_list_return_orders`, `logiwa_create_return_order`, `logiwa_cancel_return_order`
**Warehouses** — `logiwa_list_warehouses`, `logiwa_list_warehouse_locations`
**Partners** — `logiwa_list_customers`, `logiwa_list_vendors`, `logiwa_list_retailers`
**Reports** — `logiwa_report_total_inventory`, `logiwa_report_shipment_history`, `logiwa_report_receiving_history`, `logiwa_report_available_to_promise`
**Lookups** — `logiwa_lookup` (clients, warehouses, types, reasons, carriers, …)
> Tip: start with `logiwa_lookup` to resolve the `clientIdentifier`, type names, and currency ids that
> the create/update tools require.
## Development
```bash
npm run dev # tsx watch (auto-reload)
npm run build # tsc -> dist/
npm start # node dist/index.js
npx @modelcontextprotocol/inspector node dist/index.js # interactive testing
```
## Project structure
```
src/
├── index.ts # entry point: wires up tools, stdio transport, --list-tools
├── constants.ts # base URL, limits, defaults
├── types.ts # response envelope types
├── registry.ts # registerTool wrapper that records tool names
├── services/
│ ├── client.ts # auth (token fetch + cache + 401 retry) and HTTP
│ └── format.ts # list/object formatting, pagination, truncation, error messages
├── schemas/
│ └── common.ts # shared Zod fragments (pagination, line items, packing)
└── tools/ # one file per domain
├── products.ts inventory.ts shipmentOrders.ts purchaseOrders.ts
├── returnOrders.ts warehouses.ts partners.ts reports.ts helpers.ts
└── simpleList.ts # factory for simple read-only list tools
```
## Scope & notes
- Covers the **core** Logiwa domains (the API has 200+ endpoints). Niche areas — robotics, billing,
count plans, warehouse tasks, webhooks, data-setup CRUD, user/role admin — are intentionally omitted
from this first version and can be added the same way.
- Destructive operations (`*_cancel_*`, `*_remove_*`, `*_adjust_*`) are flagged with `destructiveHint`.
- For Logiwa field references, see the developer docs at <https://mydeveloper.logiwa.com/> and the
Swagger UI at <https://myapi.logiwa.com/swagger/index.html>.
## License
Licensed under the [Apache License 2.0](./LICENSE).
