katana-mcp-server 0.39.1

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. Choose Your Transport

The MCP server supports multiple transport protocols for different environments:

Transport	Use Case	Command
stdio (default)	Claude Desktop, Claude Code	katana-mcp-server
streamable-http	Claude.ai co-work, remote clients	katana-mcp-server --transport streamable-http
sse	Cursor IDE	katana-mcp-server --transport sse
http	Generic HTTP clients	katana-mcp-server --transport http

4. Use with Claude Desktop (stdio)

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!

5. Use with Claude.ai Co-work (streamable-http)

Claude.ai requires HTTPS and a publicly reachable URL. For local development, use a tunnel like ngrok:

# Terminal 1: Start the MCP server with hot-reload
uv run poe dev

# Terminal 2: Create an HTTPS tunnel
ngrok http 8765
# → Gives you https://abc123.ngrok-free.app

Then in Claude.ai:

1. Go to Customize > Connectors
2. Select "Add custom connector"
3. Paste your ngrok HTTPS URL (e.g., https://abc123.ngrok-free.app)

For production, deploy the Docker image behind a reverse proxy with TLS:

docker run -p 8765:8765 -e KATANA_API_KEY=your-key ghcr.io/dougborg/katana-mcp-server:latest

6. 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)

Endpoint Authentication (HTTP transport)

When using HTTP transport, the MCP endpoint is unauthenticated by default. Set one of the following to secure it:

Bearer token (simple, for dev/personal use):

export MCP_AUTH_TOKEN=your-secret-token

Clients must send Authorization: Bearer your-secret-token with each request. In Claude.ai, enter the token in the connector's Advanced Settings.

GitHub OAuth (production):

export MCP_GITHUB_CLIENT_ID=your-github-client-id
export MCP_GITHUB_CLIENT_SECRET=your-github-client-secret
export MCP_BASE_URL=https://your-public-url.ngrok-free.app

Create a GitHub OAuth App at https://github.com/settings/developers with the callback URL set to <MCP_BASE_URL>/auth/callback.

Auth is not required for stdio transport (local only).

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