katana-mcp-server 0.36.0

MCP server for Katana Manufacturing ERP

Katana MCP Server

Model Context Protocol (MCP) server for Katana Manufacturing ERP.

Features

• Inventory Management: Check stock, find low stock items, search items, get variant details
• Catalog Management: Create products and materials
• Order Management: Create and manage purchase orders, sales orders, and manufacturing orders
• Document Verification: Verify supplier documents against purchase orders
• Two-Step Confirmation: Preview operations before executing (elicitation pattern)
• Environment-based Authentication: Secure API key management
• Built-in Resilience: Automatic retries, rate limiting, and pagination via Python client
• Type Safety: Pydantic models for all requests and responses

Installation

pip install katana-mcp-server

Quick Start

1. Get Your Katana API Key

Obtain your API key from your Katana account settings.

2. Configure Environment

Create a .env file or set environment variable:

export KATANA_API_KEY=your-api-key-here

Or create .env file:

KATANA_API_KEY=your-api-key-here
KATANA_BASE_URL=https://api.katanamrp.com/v1  # Optional, uses default if not set

3. Use with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "katana": {
      "command": "uvx",
      "args": ["katana-mcp-server"],
      "env": {
        "KATANA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop, and you'll see Katana inventory tools available!

4. Run Standalone (Optional)

For testing or development:

export KATANA_API_KEY=your-api-key
katana-mcp-server

Available Tools

check_inventory

Check stock levels for a specific product SKU.

Parameters:

• sku (string, required): Product SKU to check

Example Request:

{
  "sku": "WIDGET-001"
}

Example Response:

{
  "sku": "WIDGET-001",
  "product_name": "Premium Widget",
  "available_stock": 150,
  "in_production": 50,
  "committed": 75
}

Use Cases:

• "What's the current stock level for SKU WIDGET-001?"
• "Check inventory for my best-selling product"
• "How much stock do we have available for order fulfillment?"

---

list_low_stock_items

Find products below a specified stock threshold.

Parameters:

• threshold (integer, optional, default: 10): Stock level threshold
• limit (integer, optional, default: 50): Maximum items to return

Example Request:

{
  "threshold": 5,
  "limit": 20
}

Example Response:

{
  "items": [
    {
      "sku": "PART-123",
      "product_name": "Component A",
      "current_stock": 3,
      "threshold": 5
    },
    {
      "sku": "PART-456",
      "product_name": "Component B",
      "current_stock": 2,
      "threshold": 5
    }
  ],
  "total_count": 15
}

Use Cases:

• "Show me products with less than 10 units in stock"
• "What items need reordering?"
• "Find critical low stock items (below 5 units)"

---

search_items

Search for items (products, materials, services) by name or SKU.

Parameters:

• query (string, required): Search term (matches name or SKU)
• limit (integer, optional, default: 20): Maximum results to return

Example Request:

{
  "query": "widget",
  "limit": 10
}

Example Response:

{
  "items": [
    {
      "id": 12345,
      "sku": "WIDGET-001",
      "name": "Premium Widget",
      "is_sellable": true,
      "stock_level": null
    },
    {
      "id": 12346,
      "sku": "WIDGET-002",
      "name": "Economy Widget",
      "is_sellable": true,
      "stock_level": null
    }
  ],
  "total_count": 2
}

Note: stock_level is always null for search results in the current implementation.

Use Cases:

• "Find all products containing 'widget'"
• "Search for SKU PART-123"
• "What items do we have for order creation?"
• "Show me all sellable products vs internal materials"

Configuration

Environment Variables

• KATANA_API_KEY (required): Your Katana API key
• KATANA_BASE_URL (optional): API base URL (default: https://api.katanamrp.com/v1)
• KATANA_MCP_LOG_LEVEL (optional): Log level - DEBUG, INFO, WARNING, ERROR (default: INFO)
• KATANA_MCP_LOG_FORMAT (optional): Log format - json, text (default: json)

Logging Configuration

The server uses structured logging with configurable output format and verbosity:

Development (verbose text logs):

export KATANA_MCP_LOG_LEVEL=DEBUG
export KATANA_MCP_LOG_FORMAT=text
katana-mcp-server

Production (structured JSON logs):

export KATANA_MCP_LOG_LEVEL=INFO
export KATANA_MCP_LOG_FORMAT=json
katana-mcp-server

See docs/LOGGING.md for complete logging documentation.

Advanced Configuration

The server uses the katana-openapi-client library with:

• Automatic retries on rate limits (429) and server errors (5xx)
• Exponential backoff with jitter
• Transparent pagination for large result sets
• 30-second default timeout

Troubleshooting

"KATANA_API_KEY environment variable is required"

Cause: API key not set in environment.

Solution: Set the environment variable or add to .env file:

export KATANA_API_KEY=your-api-key-here

"Authentication error: 401 Unauthorized"

Cause: Invalid or expired API key.

Solution: Verify your API key in Katana account settings and update the environment variable.

Tools not showing up in Claude Desktop

Cause: Configuration error or server not starting.

Solutions:

1. Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log
2. Verify configuration file syntax (valid JSON)
3. Test server standalone: katana-mcp-server (should start without errors)
4. Restart Claude Desktop after configuration changes

Rate limiting (429 errors)

Cause: Too many requests to Katana API.

Solution: The server automatically retries with exponential backoff. If you see persistent rate limiting, reduce request frequency.

Development

Prerequisites

• uv package manager - Install uv
• Python 3.12+ (for hot-reload mode)

Development Mode with Hot Reload ⚡

For rapid iteration during development, use hot-reload mode to see changes instantly without rebuilding or restarting:

# 1. Install dependencies
cd katana_mcp_server
uv sync

# 2. Install mcp-hmr (requires Python 3.12+)
uv pip install mcp-hmr

# 3. Run with hot reload
uv run mcp-hmr src/katana_mcp/server.py:mcp

Benefits:

• Edit code → Save → Changes apply instantly
• No rebuild, no reinstall, no restart needed
• Keep your Claude Desktop conversation context
• Iteration time: ~5 seconds instead of 5-10 minutes

Claude Desktop Configuration for Development:

{
  "mcpServers": {
    "katana-erp-dev": {
      "comment": "Use full path to uv - find with: which uv",
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["run", "mcp-hmr", "src/katana_mcp/server.py:mcp"],
      "cwd": "/absolute/path/to/katana-openapi-client/katana_mcp_server",
      "env": {
        "KATANA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important:

• Replace YOUR_USERNAME with your actual username
• Run which uv to find the correct uv path (usually ~/.local/bin/uv)
• Replace /absolute/path/to/ with your repository path
• Hot reload requires Python >=3.12. For Python 3.11 users, use the production install method.

See DEVELOPMENT.md for the complete development guide.

Install from Source

git clone https://github.com/dougborg/katana-openapi-client.git
cd katana-openapi-client/katana_mcp_server
uv sync

Run Tests

# Unit tests only (no API key needed)
uv run pytest tests/ -m "not integration"

# All tests (requires KATANA_API_KEY)
export KATANA_API_KEY=your-key
uv run pytest tests/

Build and Install Locally

# Build the package
uv build

# Install with pipx
pipx install --force dist/katana_mcp_server-*.whl

Version

Current version: 0.33.0

Available Tools

Inventory Tools:

• check_inventory - Check stock levels for a specific SKU
• list_low_stock_items - Find products below stock threshold
• search_items - Search for items by name or SKU
• get_variant_details - Get detailed variant information

Catalog Tools:

• create_product - Create a new product
• create_material - Create a new material

Order Tools:

• create_purchase_order - Create purchase orders with two-step confirmation
• receive_purchase_order - Receive items from purchase orders
• verify_order_document - Verify documents against purchase orders
• create_manufacturing_order - Create manufacturing orders
• create_sales_order - Create sales orders with two-step confirmation
• fulfill_order - Fulfill manufacturing or sales orders

Available Resources

Resources expose cached reference data (small, stable datasets). For transactional data (orders, stock movements), use the corresponding tools.

• katana://inventory/items - Complete catalog of products, materials, services
• katana://suppliers - Supplier directory with contact info
• katana://locations - Warehouses and facilities
• katana://tax-rates - Configured tax rates
• katana://operators - Manufacturing operators
• katana://help - Workflow guides and tool reference

Links

• Documentation: https://github.com/dougborg/katana-openapi-client
• Issue Tracker: https://github.com/dougborg/katana-openapi-client/issues
• PyPI: https://pypi.org/project/katana-mcp-server/
• Katana API: https://help.katanamrp.com/api/overview

License

MIT License - see LICENSE file for details