ConsignCloud MCP Server

A Model Context Protocol (MCP) server for the ConsignCloud API, enabling AI assistants to manage inventory, sales, accounts, and more in your consignment/retail business.

🚀 Quick Start: New to this project? See QUICK_START.md to get running in 5 minutes!

📚 Documentation

• QUICK_START.md - Get up and running in 5 minutes
• TESTING.md - Test with MCP Inspector
• CLAUDE_DESKTOP_SETUP.md - Integrate with Claude Desktop
• CONSIGNCLOUD_API_SUMMARY.md - Complete API reference
• PROJECT_SUMMARY.md - Technical overview

Features

This MCP server provides tools for:

Inventory Management

• List, create, update, and delete items
• Filter items by price, category, account, status, location
• Get inventory statistics
• Bulk edit items
• Update item statuses

Sales Management

• List and view sales
• Void and refund sales
• Filter sales by date, customer, location, status
• Get sales trends and analytics

Account Management

• Manage vendor/consignor accounts
• View account balances and statistics
• Track purchases and items per account

Additional Features

• Manage item categories
• Manage store locations
• Create and manage batches of items
• Search and suggestions across entities

Installation

1. Clone this repository:

git clone <repository-url>
cd mcp-consigncloud

2. Install dependencies:

npm install

3. Create a .env file with your ConsignCloud API credentials:

cp .env.example .env

4. Edit .env and add your API key:

CONSIGNCLOUD_API_KEY=your_api_key_here
CONSIGNCLOUD_API_BASE_URL=https://api.consigncloud.com/api/v1

Getting Your API Key

1. Log in to your ConsignCloud account
2. Navigate to Settings → Apps
3. Enable the API & Webhooks app
4. Click Add API Key
5. Copy the generated API key to your .env file

Usage

The server supports two modes:

1. STDIO Mode (for Claude Desktop)

This is the default mode for integration with Claude Desktop and other MCP clients.

Development:

npm run dev

Production:

npm run build
npm start

2. HTTP/SSE Mode (for testing with MCP Inspector)

This mode runs an HTTP server with Server-Sent Events for easy testing.

Development:

npm run dev:http

Production:

npm run build
npm run start:http

The server will run on http://localhost:3000 (configurable via .env).

Testing with MCP Inspector

See TESTING.md for detailed instructions on testing with MCP Inspector.

Quick start:

# Terminal 1: Start the HTTP server
npm run dev:http

# Terminal 2: Launch MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/sse

Using with Claude Desktop

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "consigncloud": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-consigncloud/dist/index.js"],
      "env": {
        "CONSIGNCLOUD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or if using development mode:

{
  "mcpServers": {
    "consigncloud": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/mcp-consigncloud/src/index.ts"],
      "env": {
        "CONSIGNCLOUD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Inventory Tools

• list_items - List inventory items with filters
• get_item - Get specific item details
• create_item - Create new inventory item
• update_item - Update existing item
• delete_item - Delete (soft delete) an item
• get_item_stats - Get inventory statistics

Sales Tools

• list_sales - List sales with filters
• get_sale - Get specific sale details
• void_sale - Void a sale
• get_sales_trends - Get sales analytics

Account Tools

• list_accounts - List vendor/consignor accounts
• get_account - Get specific account details
• create_account - Create new account
• update_account - Update existing account
• get_account_stats - Get account statistics

Category & Location Tools

• list_categories - List item categories
• create_category - Create new category
• list_locations - List store locations

Batch Tools

• list_batches - List item batches
• create_batch - Create new batch
• update_batch_status - Change batch status

Utility Tools

• search_suggest - Search across entities

Example Prompts

Once configured with Claude Desktop, you can use prompts like:

• "List all inventory items under $50"
• "Show me sales from last week"
• "Create a new vendor account for John Doe"
• "What are the top selling items?"
• "Show me the current balance for account ABC123"
• "Create a new batch for vendor XYZ"

API Documentation

For detailed API documentation, see CONSIGNCLOUD_API_SUMMARY.md

Currency Format

All monetary amounts are in the smallest denomination (cents for USD):

• $10.00 = 1000 cents
• $0.50 = 50 cents

Rate Limiting

The ConsignCloud API uses a leaky bucket algorithm:

• Bucket capacity: 100 requests
• Leak rate: 10 requests/second
• Exceeding limit returns 429 status

Development

Project Structure

mcp-consigncloud/
├── src/
│   ├── index.ts        # MCP server implementation
│   ├── client.ts       # ConsignCloud API client
│   └── types.ts        # TypeScript type definitions
├── dist/               # Compiled JavaScript (generated)
├── .env.example        # Environment variable template
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Watch Mode

npm run watch

Troubleshooting

API Key Issues

If you get authentication errors:

1. Verify your API key is correct in .env
2. Check that the API key hasn't been revoked in ConsignCloud
3. Ensure the API & Webhooks app is enabled in your ConsignCloud settings

Connection Issues

If the server won't start:

1. Check your .env file exists and contains valid values
2. Verify network connectivity to api.consigncloud.com
3. Check the console for specific error messages

License

ISC

Support

For ConsignCloud API issues, contact: team@consigncloud.com For MCP server issues, please open a GitHub issue.