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:

2. Install dependencies:

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

4. Edit .env and add your API key:

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:

Production:

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

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

Development:

Production:

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:

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

Or if using development mode:

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

Building

Watch Mode

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.