mcp-wms-services

rozana-dev/mcp-wms-services

3.2

If you are the rightful owner of mcp-wms-services and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An MCP server for Rozana WMS (Warehouse Management System) that facilitates communication and operations between the MCP client and the WMS.

Tools
5
Resources
0
Prompts
0

WMS Service MCP Server

PyPI - Version

An MCP server for Rozana WMS (Warehouse Management System).

Features

WMS Service Tools

Tools are callable functions that can be invoked by the MCP client to perform operations.

check_wms_health
  • Purpose: Check the health status of the WMS service
  • Authentication: Not required
  • Returns: JSON object with health status 
    {
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z"
}
  • Example Usage: "Check if the WMS service is healthy"
get_warehouse_details
  • Purpose: Get detailed information about a warehouse
  • Authentication: Required (client credentials or token)
  • Input Parameters:
    • warehouse_id (string, required): The unique identifier for the warehouse
      • Examples: "WH001", "WAREHOUSE_NYC", "ROZANA_TEST_WH1"
  • Returns: JSON object with warehouse details (name, address, capacity, etc.)
  • Example Usage: "Get details for warehouse WH001"
get_inventory_levels
  • Purpose: Get inventory levels for SKUs in a warehouse
  • Authentication: Required (client credentials or token)
  • Input Parameters:
    • warehouse_id (string, required): The unique identifier for the warehouse
    • sku (string, optional): The SKU identifier. If not provided, returns all SKUs
  • Returns: JSON object with inventory levels
  • Example Usage:
    • "Get inventory levels for warehouse WH001"
    • "Show me inventory for SKU001 in warehouse WH001"
get_orders
  • Purpose: Get order information from the WMS
  • Authentication: Required (client credentials or token)
  • Input Parameters (at least one required):
    • warehouse_id (string, optional): Filter by warehouse
    • order_id (string, optional): Get a specific order
    • status (string, optional): Filter by status (e.g., "pending", "processing", "shipped")
  • Returns: JSON object with order information
  • Example Usage:
    • "Get orders for warehouse WH001"
    • "Show me order ORD001"
    • "Get all pending orders"
get_shipments
  • Purpose: Get shipment information from the WMS
  • Authentication: Required (client credentials or token)
  • Input Parameters (at least one required):
    • warehouse_id (string, optional): Filter by warehouse
    • shipment_id (string, optional): Get a specific shipment
    • status (string, optional): Filter by status (e.g., "preparing", "in_transit", "delivered")
  • Returns: JSON object with shipment information
  • Example Usage:
    • "Get shipments for warehouse WH001"
    • "Show me shipment SHIP001"
    • "Get all in_transit shipments"

WMS Service Resources

Resources are read-only data sources that can be accessed by the MCP client.

wms-health
  • Purpose: Read-only access to WMS service health status
  • Authentication: Not required
  • URI: wms-health
  • Returns: JSON object with health status
warehouse-details/{warehouse_id}
  • Purpose: Read-only access to warehouse information
  • Authentication: Required (client credentials or token)
  • URI: warehouse-details/{warehouse_id}
    • Example: warehouse-details/WH001
  • Returns: JSON object with warehouse details
inventory-levels/{warehouse_id}
  • Purpose: Read-only access to inventory levels for all SKUs in a warehouse
  • Authentication: Required (client credentials or token)
  • URI: inventory-levels/{warehouse_id}
    • Example: inventory-levels/WH001
  • Returns: JSON object with inventory levels for all SKUs

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:

  • Returns 200 OK if the server is healthy and can connect to WMS service
  • Returns 503 Service Unavailable if the server cannot connect to WMS service

Example:

curl http://localhost:8000/health
# Response: OK - WMS service is healthy: {"status": "ok"}

Configuration

Claude Desktop Configuration

  1. Open the Claude Desktop configuration file located at:

    • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • On Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Add the following (client-credentials based):

{
  "mcpServers": {
    "mcp-wms-service": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "mcp_wms_service.main"],
      "env": {
        "WMS_BASE_URL": "https://rzn1-be.stockone.com",
        "WMS_COMPANY_CODE": "4",
        "WMS_WEB_VERSION": "v3.54.0",
        "WMS_MCP_SERVER_TRANSPORT": "stdio",
        "WMS_CLIENT_ID": "YOUR_CLIENT_ID",
        "WMS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "WMS_TOKEN_URL": "https://rzn1-be.stockone.com/o/token/",
        "WMS_PERSIST_TOKEN": "true"
      }
    }
  }
}

Update the environment variables to point to your WMS service.

  1. Locate the command entry for uv and replace it with the absolute path to the uv executable. This ensures that the correct version of uv is used when starting the server. On a Mac, you can find this path using which uv.

  2. Restart Claude Desktop to apply the changes.

Running Without uv (Using System Python)

If you prefer to use the system Python installation instead of uv, you can install the package from PyPI and run it directly:

  1. Install the package using pip:

    python3 -m pip install mcp-wms-service

    To upgrade to the latest version:

    python3 -m pip install --upgrade mcp-wms-service

  2. Update your Claude Desktop configuration to use Python directly (client credentials):

{
  "mcpServers": {
    "mcp-wms-service": {
      "command": "python3",
      "args": ["-m", "mcp_wms_service.main"],
      "env": {
        "WMS_BASE_URL": "http://localhost:8080",
        "WMS_COMPANY_CODE": "4",
        "WMS_CLIENT_ID": "YOUR_CLIENT_ID",
        "WMS_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Alternatively, you can use the installed script directly:

{
  "mcpServers": {
    "mcp-wms-service": {
      "command": "mcp-wms-service",
      "env": {
        "WMS_BASE_URL": "http://localhost:8080",
        "WMS_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Note: Make sure to use the full path to the Python executable or the mcp-wms-service script if they are not in your system PATH. You can find the paths using:

  • which python3 for the Python executable
  • which mcp-wms-service for the installed script

Development

Using Docker (Recommended)

  1. Clone the repository:

    git clone https://github.com/varma-rozana/mcp-wms-service.git
cd mcp-wms-service

  2. Copy the example environment file and configure it:

    cp .env.example .env
# Edit .env with your WMS service URL and API token

  3. Build and run with Docker Compose:

    docker-compose up -d

  4. Check the health endpoint:

    curl http://localhost:8365/health

  5. View logs:

    docker-compose logs -f

  6. Stop the service:

    docker-compose down

Using Docker (Manual)

  1. Build the Docker image:

    docker build -t mcp-wms-service .

  2. Run the container:

docker run -d
-p 8000:8000
-e WMS_BASE_URL=http://localhost:8080
-e WMS_CLIENT_ID=your-client-id
-e WMS_CLIENT_SECRET=your-client-secret
-e WMS_TOKEN_URL=http://localhost:8080/o/token/
-e WMS_MCP_SERVER_TRANSPORT=http
-e WMS_MCP_BIND_HOST=0.0.0.0
--name mcp-wms-service
mcp-wms-service


### Local Development (Without Docker)

1. Clone the repository:
```bash
git clone https://github.com/varma-rozana/mcp-wms-service.git
cd mcp-wms-service

  1. Add the following variables to a .env file in the root of the repository (client credentials preferred):

    WMS_BASE_URL=http://localhost:8080
WMS_CLIENT_ID=your-client-id
WMS_CLIENT_SECRET=your-client-secret
# Optional: override token endpoint and persist token to .env
WMS_TOKEN_URL=http://localhost:8080/o/token/
WMS_PERSIST_TOKEN=true

  2. Install dependencies:

    Option 1: Using uv (recommended)

    # Install uv: https://docs.astral.sh/uv/
uv sync
source .venv/bin/activate

    Option 2: Using pip

    pip install -r requirements.txt
# For development dependencies:
pip install -r requirements-dev.txt

  3. For easy testing with the MCP Inspector, run fastmcp dev mcp_wms_service/mcp_server.py to start the MCP server.

  4. To test with HTTP transport and the health check endpoint:

    # Using default port 8000
WMS_MCP_SERVER_TRANSPORT=http python -m mcp_wms_service.main

# Or with a custom port
WMS_MCP_SERVER_TRANSPORT=http WMS_MCP_BIND_PORT=4200 python -m mcp_wms_service.main

# Then in another terminal:
curl http://localhost:8000/health  # or http://localhost:4200/health for custom port

Environment Variables

The following environment variables are used to configure the WMS service connection:

Client-credentials authentication (preferred)
  • WMS_CLIENT_ID: OAuth client id (required)
  • WMS_CLIENT_SECRET: OAuth client secret (required)
  • WMS_TOKEN_URL: Token endpoint (optional)
    • Default: {WMS_BASE_URL}/o/token/
  • WMS_PERSIST_TOKEN: Persist acquired token to .env (optional)
    • Accepts: true|false (default: false)
Token (fallback/override)
  • WMS_API_TOKEN: API token to send in authorization header (optional)
    • If set, will be used; otherwise, the server auto-logins with client credentials.
General
  • WMS_BASE_URL: The base URL of the WMS service
    • Default: http://localhost:8080
  • WMS_TIMEOUT: Request timeout in seconds (default: 30)
  • WMS_MCP_SERVER_TRANSPORT: MCP server transport (default: stdio) — one of stdio, http, sse
  • WMS_MCP_BIND_HOST: Bind host for HTTP/SSE (default: 127.0.0.1)
  • WMS_MCP_BIND_PORT: Bind port for HTTP/SSE (default: 8000)
Example Configurations

For local development (client credentials):

WMS_BASE_URL=http://localhost:8080
WMS_CLIENT_ID=your-dev-client-id
WMS_CLIENT_SECRET=your-dev-client-secret

For production WMS service (client credentials):

# Production configuration
WMS_BASE_URL=https://wms.rozana.in
WMS_CLIENT_ID=your-prod-client-id
WMS_CLIENT_SECRET=your-prod-client-secret
WMS_TIMEOUT=60

For MCP Inspector or remote access with HTTP transport (client credentials):

WMS_BASE_URL=http://localhost:8080
WMS_CLIENT_ID=your-client-id
WMS_CLIENT_SECRET=your-client-secret
WMS_MCP_SERVER_TRANSPORT=http
WMS_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
WMS_MCP_BIND_PORT=4200  # Custom port (default: 8000)

When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:

  • MCP endpoint: http://localhost:4200/mcp
  • Health check: http://localhost:4200/health

You can set these variables in your environment, in a .env file, or in the Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-wms-service": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "mcp_wms_service.main"],
      "env": {
        "WMS_BASE_URL": "http://localhost:8080",
        "WMS_CLIENT_ID": "your-client-id",
        "WMS_CLIENT_SECRET": "your-client-secret",
        "WMS_TIMEOUT": "30",
        "WMS_MCP_SERVER_TRANSPORT": "stdio",
        "WMS_MCP_BIND_HOST": "127.0.0.1",
        "WMS_MCP_BIND_PORT": "8000"
      }
    }
  }
}

Note: The bind host and port settings are only used when transport is set to "http" or "sse".

Usage Examples

Once configured in Claude Desktop, you can use natural language to interact with your WMS service:

Check Health

"Check if the WMS service is healthy"

Get Warehouse Details

"Get details for warehouse WH001"
"Show me information about warehouse ROZANA_TEST_WH1"

Get Inventory Levels

"Get inventory levels for warehouse WH001"
"Show me inventory for SKU001 in warehouse WH001"
"What is the stock level of ROZ001 in ROZANA_TEST_WH1?"

Get Orders

"Get orders for warehouse WH001"
"Show me order ORD001"
"Get all pending orders"
"Get processing orders for warehouse WH001"

Get Shipments

"Get shipments for warehouse WH001"
"Show me shipment SHIP001"
"Get all in_transit shipments"
"Get preparing shipments for warehouse WH001"

API Endpoints Reference

1. Health Check

curl -X GET http://localhost:8080/api/health

2. Get Warehouse Details

curl -X GET "http://localhost:8080/api/warehouse/details?warehouse_id=WH001" \
  -H "authorization: YOUR_API_TOKEN"

3. Get Inventory Levels

# Get all SKUs
curl -X GET "http://localhost:8080/api/inventory/levels?warehouse_id=WH001" \
  -H "authorization: YOUR_API_TOKEN"

# Get specific SKU
curl -X GET "http://localhost:8080/api/inventory/levels?warehouse_id=WH001&sku=SKU001" \
  -H "authorization: YOUR_API_TOKEN"

4. Get Orders

# Get orders by warehouse
curl -X GET "http://localhost:8080/api/orders?warehouse_id=WH001" \
  -H "authorization: YOUR_API_TOKEN"

# Get specific order
curl -X GET "http://localhost:8080/api/orders?order_id=ORD001" \
  -H "authorization: YOUR_API_TOKEN"

# Get orders by status
curl -X GET "http://localhost:8080/api/orders?status=pending" \
  -H "authorization: YOUR_API_TOKEN"

5. Get Shipments

# Get shipments by warehouse
curl -X GET "http://localhost:8080/api/shipments?warehouse_id=WH001" \
  -H "authorization: YOUR_API_TOKEN"

# Get specific shipment
curl -X GET "http://localhost:8080/api/shipments?shipment_id=SHIP001" \
  -H "authorization: YOUR_API_TOKEN"

# Get shipments by status
curl -X GET "http://localhost:8080/api/shipments?status=in_transit" \
  -H "authorization: YOUR_API_TOKEN"

Authentication

  • Preferred: Set WMS_CLIENT_ID and WMS_CLIENT_SECRET. The server will automatically obtain an access token from WMS_TOKEN_URL (default {WMS_BASE_URL}/o/token/), use it for requests, and optionally persist it to .env if WMS_PERSIST_TOKEN=true.
  • Optional: Set WMS_API_TOKEN to use a static token directly. If both are present, the token will be used; otherwise the client-credentials flow runs.
  • Headers: The server sends lowercase authorization without Bearer.
  • 401 handling: With client credentials configured, the server will attempt a token refresh once on 401 and retry the request.

check_wms_health does not require authentication. All other tools require authentication.

Resources vs Tools

Tools

Tools are callable functions that can perform operations and return results. They are invoked directly by the MCP client.

Resources

Resources are read-only data sources that can be accessed by URI. They provide a way to expose data that the MCP client can reference.

Both tools and resources can access the same underlying WMS APIs, but they serve different purposes:

  • Use tools when you need to perform an operation or pass parameters
  • Use resources when you need to reference data by URI

Linting

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.