Kibo Commerce MCP Server

⚠️ DEPRECATED: This package is deprecated and no longer maintained. Please use the official Kibo MCP Server instead.

Replacement: https://docs.kibocommerce.com/pages/kibo-mcp-server

This repository and npm package will no longer receive updates or security fixes.

A Model Context Protocol (MCP) server providing seamless integration with Kibo Commerce platform through their TypeScript SDK.

Features

• 🛍️ Product Management: Search, retrieve, and analyze product catalogs with advanced filtering

• 📦 Order Operations: Complete order lifecycle management from search to fulfillment

• 👥 Customer Management: Comprehensive customer data access and order history

• 📊 Inventory Operations: Real-time inventory tracking across multiple locations

• 🔧 Site Configuration: Access to site settings and configuration data

• 🔐 Secure Authentication: OAuth2 with automatic token refresh and management

• 📱 Multi-tenant Support: Support for multiple Kibo Commerce environments

Quick Start

Prerequisites

• Node.js 18+ and npm

• Kibo Commerce tenant with API access

• Claude Desktop or compatible MCP client

Installation

Option 1: NPX (Recommended - No Installation Required)

No installation needed! NPX automatically downloads and runs the latest version from npm registry.

Benefits:

• ✅ Always uses the latest version

• ✅ No global package pollution

• ✅ Works immediately without setup

• ✅ Automatic updates

Option 2: NPM Global Install

npm install -g @kibocommerce/kibo-commerce-mcp

Option 3: Clone and Build

git clone https://github.com/kibocommerce/kibo-commerce-mcp.git
cd kibo-commerce-mcp
npm install
npm run build

Configuration

1. Get Kibo Commerce Credentials

   • Log into your Kibo Commerce Admin Console

   • Navigate to System > Applications

   • Create or use existing application credentials

   • Note: Client ID, Client Secret, Tenant ID, Site ID, API Host

2. Environment Setup

Create a .env file:

KIBO_API_HOST=https://t{tenant}.sandbox.mozu.com
KIBO_CLIENT_ID=your_application_id
KIBO_CLIENT_SECRET=your_shared_secret  
KIBO_TENANT_ID=12345
KIBO_SITE_ID=67890
KIBO_MASTER_CATALOG_ID=1
KIBO_LOCALE=en-US
KIBO_CURRENCY=USD

Claude Desktop Setup

Configuration File Locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: NPX (Recommended)

{
  "mcpServers": {
    "kibo-commerce": {
      "command": "npx",
      "args": ["@kibocommerce/kibo-commerce-mcp"],
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.sandbox.mozu.com",
        "KIBO_CLIENT_ID": "your_application_id",
        "KIBO_CLIENT_SECRET": "your_shared_secret",
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890"
      }
    }
  }
}

Option 2: NPM Global Install

{
  "mcpServers": {
    "kibo-commerce": {
      "command": "kibo-commerce-mcp",
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.sandbox.mozu.com",
        "KIBO_CLIENT_ID": "your_application_id",
        "KIBO_CLIENT_SECRET": "your_shared_secret",
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890"
      }
    }
  }
}

Option 3: Local Development

{
  "mcpServers": {
    "kibo-commerce": {
      "command": "node",
      "args": ["/absolute/path/to/kibo-commerce-mcp/dist/index.js"],
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.sandbox.mozu.com",
        "KIBO_CLIENT_ID": "your_application_id", 
        "KIBO_CLIENT_SECRET": "your_shared_secret",
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890"
      }
    }
  }
}

Option 4: Multiple Environments

{
  "mcpServers": {
    "kibo-production": {
      "command": "npx",
      "args": ["@kibocommerce/kibo-commerce-mcp"],
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.mozu.com",
        "KIBO_CLIENT_ID": "prod_client_id",
        "KIBO_CLIENT_SECRET": "prod_client_secret",
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890"
      }
    },
    "kibo-sandbox": {
      "command": "npx",
      "args": ["@kibocommerce/kibo-commerce-mcp"],
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.sandbox.mozu.com",
        "KIBO_CLIENT_ID": "sandbox_client_id",
        "KIBO_CLIENT_SECRET": "sandbox_client_secret",
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890"
      }
    }
  }
}

Testing the Connection

1. Restart Claude Desktop after configuration changes

2. First-time NPX users: The first run may take a few seconds to download the package

3. Test with a simple query:

   Search for products containing "shirt" 

4. Verify tools are loaded:

   What Kibo Commerce tools are available?

Available Tools

🛍️ Product Operations

• kibo_product_search - Search products with advanced filtering, pagination, and sorting

• kibo_product_details - Get detailed product information including variations, pricing, and inventory

• kibo_category_list - Retrieve product categories and category tree structure

📦 Order Operations

• kibo_order_search - Search orders by customer, status, date range with pagination

• kibo_order_details - Get complete order information including items, payments, and fulfillment

• kibo_order_status_update - Update order status with optional notes and audit trail

👥 Customer Operations

• kibo_customer_search - Search customers with filtering by email, name, and status

• kibo_customer_details - Get detailed customer profiles including attributes and contacts

• kibo_customer_order_history - Retrieve complete customer order history with filtering

📊 Inventory Operations

• kibo_inventory_search - Search inventory levels across products and locations

• kibo_inventory_details - Get detailed inventory information with transaction history

• kibo_stock_availability - Check stock availability for multiple products

Example Usage

Product Search

Find all laptops under $2000 in the electronics category, sorted by price

Order Management

Show me all pending orders from the last 7 days that need immediate attention

Customer Service

Look up customer "john@example.com" and show their order history from the last 6 months

Inventory Analysis

Check inventory levels for products "SKU-001", "SKU-002", "SKU-003" at warehouse location "WH-MAIN"

Troubleshooting

Common Issues

Authentication Errors

• 401 Unauthorized: Check Client ID/Secret and ensure application permissions

• 403 Forbidden: Verify user account has access to requested resources

• Invalid Host: Ensure API Host URL matches your environment (sandbox vs production)

Network Issues

• Connection Timeout: Check firewall/proxy settings

• DNS Resolution: Verify API host URL is accessible

• SSL Issues: Ensure valid certificates for HTTPS connections

Tool Errors

• Tool Not Found: Restart Claude Desktop after configuration changes

• Empty Results: Verify data exists in your Kibo Commerce tenant

• Permission Denied: Check application API permissions in Kibo Admin

Debug Mode

Enable detailed logging:

{
  "mcpServers": {
    "kibo-commerce": {
      "command": "npx",
      "args": ["@kibocommerce/kibo-commerce-mcp"],
      "env": {
        "KIBO_API_HOST": "https://t{tenant}.sandbox.mozu.com",
        "KIBO_CLIENT_ID": "your_application_id",
        "KIBO_CLIENT_SECRET": "your_shared_secret", 
        "KIBO_TENANT_ID": "12345",
        "KIBO_SITE_ID": "67890",
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Support

• 📚 Documentation

• 🐛 Issue Tracker

• 💬 Discussions

Development

Local Development Setup

# Clone repository
git clone https://github.com/kibocommerce/kibo-commerce-mcp.git
cd kibo-commerce-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

# Development mode with auto-rebuild
npm run dev

Project Structure

kibo-commerce-mcp/
├── src/
│   ├── auth/           # Authentication services
│   ├── tools/          # MCP tool implementations  
│   ├── types/          # TypeScript type definitions
│   ├── services/       # Kibo API service wrappers
│   └── index.ts        # Main server entry point
├── docs/               # Documentation
├── examples/           # Usage examples
├── tests/              # Test suite
└── dist/               # Built JavaScript (generated)

Adding New Tools

1. Create tool implementation in src/tools/

2. Add tool registration in src/index.ts

3. Update type definitions in src/types/

4. Add tests in tests/

5. Update documentation

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint
npm run lint:fix

Publishing for NPX Usage

To make the package available for npx usage:

# Build the package
npm run build

# Publish to npm registry
npm publish

# Users can then run with npx
npx @kibocommerce/kibo-commerce-mcp

Note: The package must be published to npm registry for npx to work. For development, use the local development option in Claude Desktop configuration.

API Reference

Authentication

• OAuth2 client credentials flow

• Automatic token refresh with 5-minute buffer

• Multi-tenant support with context headers

• Secure credential management

Rate Limiting

• Automatic retry with exponential backoff

• Request queuing for high-volume operations

• Error handling for rate limit exceeded responses

Data Models

• Comprehensive TypeScript types for all Kibo Commerce entities

• Validation schemas using Zod for runtime type checking

• Consistent response formatting across all tools

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Code Standards

• TypeScript with strict type checking

• ESLint with recommended rules

• Jest for testing with 80%+ coverage

• Conventional Commits for commit messages

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Kibo Commerce for the e-commerce platform

• Model Context Protocol for the integration framework

• Anthropic for Claude Desktop and MCP ecosystem