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:

With custom configuration (CLI flags override environment variables):

With absolute path:

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

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

Recommended: Using .env file

Alternative: Inline environment variables

See CLAUDE_DESKTOP_SETUP.md for detailed setup instructions.

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. The HTTP server validates API connection on startup and shows clear error messages

HTTP/SSE Server Features

The HTTP server includes:

• ✅ Startup validation - Tests API connection before accepting requests

• ✅ CLI arguments - Override env vars with --api-key, --port, --host

• ✅ Detailed errors - Comprehensive error messages with HTTP status codes

• ✅ Session management - Proper SSE session handling

• ✅ Health endpoint - /health for monitoring

• ✅ Masked logging - API keys are partially hidden in logs

License

ISC

Support

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