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

With custom configuration (CLI flags override environment variables):

node dist/http-server.js --api-key YOUR_KEY --port 3001 --host localhost

With absolute path:

/opt/homebrew/bin/node /absolute/path/to/dist/http-server.js --api-key YOUR_KEY

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:

# Option 1: HTTP/SSE mode
# Terminal 1: Start the HTTP server
npm run start:http

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

# Option 2: stdio mode (uses .env file)
npx @modelcontextprotocol/inspector node /absolute/path/to/dist/index.js

# Option 3: stdio mode with environment variable
CONSIGNCLOUD_API_KEY=your_key npx @modelcontextprotocol/inspector node dist/index.js

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

{
  "mcpServers": {
    "consigncloud": {
      "command": "node",
      "args": ["/Users/administrators/Documents/Workspace/github/mcp-consigncloud/dist/index.js"]
    }
  }
}

Alternative: Inline environment variables

{
  "mcpServers": {
    "consigncloud": {
      "command": "node",
      "args": ["/Users/administrators/Documents/Workspace/github/mcp-consigncloud/dist/index.js"],
      "env": {
        "CONSIGNCLOUD_API_KEY": "your_api_key_here"
      }
    }
  }
}

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

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. 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: [email protected] For MCP server issues, please open a GitHub issue.