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:

Go to Customize > Connectors
Select "Add custom connector"
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, and corrections — 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_CACHE_DIR (optional): Directory for the typed-cache SQLite file. Defaults to a shared machine-wide cache dir (~/Library/Caches/katana-mcp on macOS) so multiple server instances share one warm cache — concurrency-safe via WAL + a 30s busy_timeout. Set this only for hard isolation (a separate DB per connector, e.g. a dev tenant that must not share prod state). See docs/development.md.
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:

Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log
Verify configuration file syntax (valid JSON)
Test server standalone: katana-mcp-server (should start without errors)
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

License

MIT License - see LICENSE file for details

Metadata

Release files for katana-mcp-server 0.121.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for katana-mcp-server 0.121.1
File	Size	Uploaded
katana_mcp_server-0.121.1.tar.gz	1.3 MB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for katana-mcp-server 0.121.1
File	Interpreter	ABI	Platform	Reset
katana_mcp_server-0.121.1-py3-none-any.whl 595.5 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 1.9 MB

Release files / katana_mcp_server-0.121.1.tar.gz

Download URL	katana_mcp_server-0.121.1.tar.gz
Size	1.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`8e8b76ad98dfc427329d1c9e8cccbc6f8662d8d44b27804c98258ed2568f5ef1`
BLAKE2b-256 checksum How to use checksums	`ddf9573161133589f9ece390b753c78227459b5daa1198a4fe236661eed0ed5c`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dougborg/katana-openapi-client
Publishing commit: github.com/dougborg/katana-openapi-client/tree/a00e75c42278912ebb3b294690bb69be9d130894

Workflow

Publishing configuration: github.com/dougborg/katana-openapi-client/blob/a00e75c42278912ebb3b294690bb69be9d130894/.github/workflows/publish.yml
Publishing logs: github.com/dougborg/katana-openapi-client/actions/runs/37539774983/attempts/1

Artifact

Subject: katana_mcp_server-0.121.1.tar.gz
SHA-256 checksum: 8e8b76ad98dfc427329d1c9e8cccbc6f8662d8d44b27804c98258ed2568f5ef1 Verifying attestations

Release files / katana_mcp_server-0.121.1-py3-none-any.whl

Download URL	katana_mcp_server-0.121.1-py3-none-any.whl
Size	595.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`de87258e7c3e2d56d196383f8284e0d2c68ed00827df80d45df7bdb1ab3553a4`
BLAKE2b-256 checksum How to use checksums	`c771de633899e37b533e087d9a3e4a8e366284dcffa5fc218c4f285091116587`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dougborg/katana-openapi-client
Publishing commit: github.com/dougborg/katana-openapi-client/tree/a00e75c42278912ebb3b294690bb69be9d130894

Workflow

Publishing configuration: github.com/dougborg/katana-openapi-client/blob/a00e75c42278912ebb3b294690bb69be9d130894/.github/workflows/publish.yml
Publishing logs: github.com/dougborg/katana-openapi-client/actions/runs/37539774983/attempts/1

Artifact

Subject: katana_mcp_server-0.121.1-py3-none-any.whl
SHA-256 checksum: de87258e7c3e2d56d196383f8284e0d2c68ed00827df80d45df7bdb1ab3553a4 Verifying attestations