katana-mcp-server 0.77.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, modify, and fulfill purchase orders, sales orders, and manufacturing orders; correct shipped builds
• Document Verification: Verify supplier documents against purchase orders
• Preview / Apply Pattern: Two-step confirmation for every write operation — preview returns a Prefab UI card with Confirm/Cancel; apply executes
• 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
• Typed SQLite Cache: Local mirror of catalog and transactional entities (items, suppliers, customers, locations, sales / purchase / manufacturing orders, stock transfers and adjustments) with FTS5 fuzzy search, soft-state filtering, and cold-cache recovery — see docs/typed_cache/

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 and Resources

The server's tool surface covers inventory, catalog, orders (sales / purchase / manufacturing), stock movement, fulfillment, corrections, and reporting — plus resources for cached reference data and a built-in help system.

The live, always-current tool and resource lists are exposed by the server itself:

• katana://help — workflow overview and quick reference
• katana://help/tools — every registered tool with its parameters and docstring
• katana://help/resources — every registered resource

These resources are the authoritative source — reach for them rather than any hand-maintained list, which would drift on every release. From an MCP host (Claude Desktop, Claude.ai, etc.) the tool list also shows up in the host's UI once the server is connected, and mcp inspect / fastmcp dev give the same view from the command line.

Every write tool follows the preview / apply pattern: calling with preview=true (the default) returns a Prefab UI card with Confirm/Cancel buttons; calling with preview=false executes. The destructive-hint annotation also signals to the host to ask the user before invocation. See docs/prefab/README.md for the card pattern details.

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 docs/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

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