# Katana MCP Server
Model Context Protocol (MCP) server for Katana Manufacturing ERP.
## Features
- **Inventory Management**: Check stock levels, find low stock items, search products
- **Environment-based Authentication**: Secure API key management
- **Built-in Resilience**: Automatic retries, rate limiting, and pagination
- **Type Safety**: Pydantic models for all requests and responses
## Installation
```bash
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:
```bash
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):
```json
{
"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:
```bash
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**:
```json
{
"sku": "WIDGET-001"
}
```
**Example Response**:
```json
{
"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**:
```json
{
"threshold": 5,
"limit": 20
}
```
**Example Response**:
```json
{
"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_products
Search for products 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**:
```json
{
"query": "widget",
"limit": 10
}
```
**Example Response**:
```json
{
"products": [
{
"id": 12345,
"sku": "WIDGET-001",
"name": "Premium Widget",
"is_sellable": true,
"stock_level": 150
},
{
"id": 12346,
"sku": "WIDGET-002",
"name": "Economy Widget",
"is_sellable": true,
"stock_level": 200
}
],
"total_count": 2
}
```
**Use Cases**:
- "Find all products containing 'widget'"
- "Search for SKU PART-123"
- "What products do we have in the electronics category?"
## Configuration
### Environment Variables
- `KATANA_API_KEY` (required): Your Katana API key
- `KATANA_BASE_URL` (optional): API base URL (default: https://api.katanamrp.com/v1)
### Advanced Configuration
The server uses the [katana-openapi-client](https://pypi.org/project/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:
```bash
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
### Install from Source
```bash
git clone https://github.com/dougborg/katana-openapi-client.git
cd katana-openapi-client/katana_mcp_server
uv sync
```
### Run Tests
```bash
# 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/
```
### Local Development
```bash
# Run server in development mode
uv run python -m katana_mcp
```
## Version
Current version: **0.1.0a1** (alpha release)
This is an alpha release with 3 inventory management tools. Future releases will add:
- Sales order management
- Purchase order management
- Manufacturing order management
- Custom resources and prompts
## 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
Raw data
{
"_id": null,
"home_page": null,
"name": "katana-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": "Doug Borg <dougborg@dougborg.org>",
"keywords": "ai-tools, claude, erp, katana, manufacturing, mcp, mcp-server, model-context-protocol",
"author": null,
"author_email": "Doug Borg <dougborg@dougborg.org>",
"download_url": "https://files.pythonhosted.org/packages/43/51/f484dcdd32822022bb8b5b183b6163ba8c7d775e55ab37a8f0af9ba21a94/katana_mcp_server-0.2.1.tar.gz",
"platform": null,
"description": "# Katana MCP Server\n\nModel Context Protocol (MCP) server for Katana Manufacturing ERP.\n\n## Features\n\n- **Inventory Management**: Check stock levels, find low stock items, search products\n- **Environment-based Authentication**: Secure API key management\n- **Built-in Resilience**: Automatic retries, rate limiting, and pagination\n- **Type Safety**: Pydantic models for all requests and responses\n\n## Installation\n\n```bash\npip install katana-mcp-server\n```\n\n## Quick Start\n\n### 1. Get Your Katana API Key\n\nObtain your API key from your Katana account settings.\n\n### 2. Configure Environment\n\nCreate a `.env` file or set environment variable:\n\n```bash\nexport KATANA_API_KEY=your-api-key-here\n```\n\nOr create `.env` file:\n\n```\nKATANA_API_KEY=your-api-key-here\nKATANA_BASE_URL=https://api.katanamrp.com/v1 # Optional, uses default if not set\n```\n\n### 3. Use with Claude Desktop\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"katana\": {\n \"command\": \"uvx\",\n \"args\": [\"katana-mcp-server\"],\n \"env\": {\n \"KATANA_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop, and you'll see Katana inventory tools available!\n\n### 4. Run Standalone (Optional)\n\nFor testing or development:\n\n```bash\nexport KATANA_API_KEY=your-api-key\nkatana-mcp-server\n```\n\n## Available Tools\n\n### check_inventory\n\nCheck stock levels for a specific product SKU.\n\n**Parameters**:\n- `sku` (string, required): Product SKU to check\n\n**Example Request**:\n```json\n{\n \"sku\": \"WIDGET-001\"\n}\n```\n\n**Example Response**:\n```json\n{\n \"sku\": \"WIDGET-001\",\n \"product_name\": \"Premium Widget\",\n \"available_stock\": 150,\n \"in_production\": 50,\n \"committed\": 75\n}\n```\n\n**Use Cases**:\n- \"What's the current stock level for SKU WIDGET-001?\"\n- \"Check inventory for my best-selling product\"\n- \"How much stock do we have available for order fulfillment?\"\n\n---\n\n### list_low_stock_items\n\nFind products below a specified stock threshold.\n\n**Parameters**:\n- `threshold` (integer, optional, default: 10): Stock level threshold\n- `limit` (integer, optional, default: 50): Maximum items to return\n\n**Example Request**:\n```json\n{\n \"threshold\": 5,\n \"limit\": 20\n}\n```\n\n**Example Response**:\n```json\n{\n \"items\": [\n {\n \"sku\": \"PART-123\",\n \"product_name\": \"Component A\",\n \"current_stock\": 3,\n \"threshold\": 5\n },\n {\n \"sku\": \"PART-456\",\n \"product_name\": \"Component B\",\n \"current_stock\": 2,\n \"threshold\": 5\n }\n ],\n \"total_count\": 15\n}\n```\n\n**Use Cases**:\n- \"Show me products with less than 10 units in stock\"\n- \"What items need reordering?\"\n- \"Find critical low stock items (below 5 units)\"\n\n---\n\n### search_products\n\nSearch for products by name or SKU.\n\n**Parameters**:\n- `query` (string, required): Search term (matches name or SKU)\n- `limit` (integer, optional, default: 20): Maximum results to return\n\n**Example Request**:\n```json\n{\n \"query\": \"widget\",\n \"limit\": 10\n}\n```\n\n**Example Response**:\n```json\n{\n \"products\": [\n {\n \"id\": 12345,\n \"sku\": \"WIDGET-001\",\n \"name\": \"Premium Widget\",\n \"is_sellable\": true,\n \"stock_level\": 150\n },\n {\n \"id\": 12346,\n \"sku\": \"WIDGET-002\",\n \"name\": \"Economy Widget\",\n \"is_sellable\": true,\n \"stock_level\": 200\n }\n ],\n \"total_count\": 2\n}\n```\n\n**Use Cases**:\n- \"Find all products containing 'widget'\"\n- \"Search for SKU PART-123\"\n- \"What products do we have in the electronics category?\"\n\n## Configuration\n\n### Environment Variables\n\n- `KATANA_API_KEY` (required): Your Katana API key\n- `KATANA_BASE_URL` (optional): API base URL (default: https://api.katanamrp.com/v1)\n\n### Advanced Configuration\n\nThe server uses the [katana-openapi-client](https://pypi.org/project/katana-openapi-client/) library with:\n- Automatic retries on rate limits (429) and server errors (5xx)\n- Exponential backoff with jitter\n- Transparent pagination for large result sets\n- 30-second default timeout\n\n## Troubleshooting\n\n### \"KATANA_API_KEY environment variable is required\"\n\n**Cause**: API key not set in environment.\n\n**Solution**: Set the environment variable or add to `.env` file:\n```bash\nexport KATANA_API_KEY=your-api-key-here\n```\n\n### \"Authentication error: 401 Unauthorized\"\n\n**Cause**: Invalid or expired API key.\n\n**Solution**: Verify your API key in Katana account settings and update the environment variable.\n\n### Tools not showing up in Claude Desktop\n\n**Cause**: Configuration error or server not starting.\n\n**Solutions**:\n1. Check Claude Desktop logs: `~/Library/Logs/Claude/mcp*.log`\n2. Verify configuration file syntax (valid JSON)\n3. Test server standalone: `katana-mcp-server` (should start without errors)\n4. Restart Claude Desktop after configuration changes\n\n### Rate limiting (429 errors)\n\n**Cause**: Too many requests to Katana API.\n\n**Solution**: The server automatically retries with exponential backoff. If you see persistent rate limiting, reduce request frequency.\n\n## Development\n\n### Install from Source\n\n```bash\ngit clone https://github.com/dougborg/katana-openapi-client.git\ncd katana-openapi-client/katana_mcp_server\nuv sync\n```\n\n### Run Tests\n\n```bash\n# Unit tests only (no API key needed)\nuv run pytest tests/ -m \"not integration\"\n\n# All tests (requires KATANA_API_KEY)\nexport KATANA_API_KEY=your-key\nuv run pytest tests/\n```\n\n### Local Development\n\n```bash\n# Run server in development mode\nuv run python -m katana_mcp\n```\n\n## Version\n\nCurrent version: **0.1.0a1** (alpha release)\n\nThis is an alpha release with 3 inventory management tools. Future releases will add:\n- Sales order management\n- Purchase order management\n- Manufacturing order management\n- Custom resources and prompts\n\n## Links\n\n- **Documentation**: https://github.com/dougborg/katana-openapi-client\n- **Issue Tracker**: https://github.com/dougborg/katana-openapi-client/issues\n- **PyPI**: https://pypi.org/project/katana-mcp-server/\n- **Katana API**: https://help.katanamrp.com/api/overview\n\n## License\n\nMIT License - see LICENSE file for details\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Katana Manufacturing ERP",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/dougborg/katana-openapi-client/issues",
"Documentation": "https://dougborg.github.io/katana-openapi-client/",
"Homepage": "https://github.com/dougborg/katana-openapi-client",
"Repository": "https://github.com/dougborg/katana-openapi-client"
},
"split_keywords": [
"ai-tools",
" claude",
" erp",
" katana",
" manufacturing",
" mcp",
" mcp-server",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58751716a694f3db445757a122e725db6a2309c480dcca4b8199cf75e7fcc560",
"md5": "1cb4bc306516a53975dc199b508b2c12",
"sha256": "fe911fb2ce975a201987aacc444ab3dc8e15db72ad9a1ddd1c021e39e040b03a"
},
"downloads": -1,
"filename": "katana_mcp_server-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cb4bc306516a53975dc199b508b2c12",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 10473,
"upload_time": "2025-10-28T12:20:12",
"upload_time_iso_8601": "2025-10-28T12:20:12.541324Z",
"url": "https://files.pythonhosted.org/packages/58/75/1716a694f3db445757a122e725db6a2309c480dcca4b8199cf75e7fcc560/katana_mcp_server-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4351f484dcdd32822022bb8b5b183b6163ba8c7d775e55ab37a8f0af9ba21a94",
"md5": "b31fa62017dec1dd090971b981deca40",
"sha256": "bdae026e615540897641427db38b55bb7b40841b6b87ba2d9100e4913521e93e"
},
"downloads": -1,
"filename": "katana_mcp_server-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "b31fa62017dec1dd090971b981deca40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 19128,
"upload_time": "2025-10-28T12:20:13",
"upload_time_iso_8601": "2025-10-28T12:20:13.863174Z",
"url": "https://files.pythonhosted.org/packages/43/51/f484dcdd32822022bb8b5b183b6163ba8c7d775e55ab37a8f0af9ba21a94/katana_mcp_server-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 12:20:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dougborg",
"github_project": "katana-openapi-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "katana-mcp-server"
}
JSON
