Skip to main content
Glama
ConsignCloud MCP Server

ConsignCloud MCP Server

by modellers

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

Related MCP server: FacturaHub MCP Server

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
  1. Install dependencies:

npm install
  1. Create a .env file with your ConsignCloud API credentials:

cp .env.example .env
  1. 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: team@consigncloud.com For MCP server issues, please open a GitHub issue.

Available Tools

26 tools
calculate_account_metricsC

Calculate comprehensive metrics for a specific vendor/consignor account including current balance, inventory value, items available/sold, total sales revenue, and commission owed.

Inputs: account_id (required), date_from, date_to, inventory_type.

calculate_inventory_valueB

Calculate total inventory value with comprehensive filtering and grouping. Returns total value, item count, average value, and optional breakdown by category, location, account, inventory type, or status.

Inputs: status, category, account, location, +7 more.

calculate_sales_totalsC

Calculate sales totals with filtering by date range, status, location, customer, payment type, and amount. Returns total revenue, tax, sale count, average sale value, and optional breakdown by status, location, or date period.

Inputs: status, location, customer, date_from, +6 more.

create_accountC

Create a new vendor/consignor account

Inputs: first_name, last_name, company, email, +3 more.

create_batchC

Create a new batch of items

Inputs: description, account.

create_categoryC

Create a new item category

Inputs: name (required).

create_itemC

Create a new inventory item

Inputs: title (required), tag_price (required), description, category, +5 more.

delete_itemB

Delete (soft delete) an inventory item

Inputs: id (required).

get_accountC

Get details of a specific account

Inputs: id (required).

get_account_statsC

Get statistics for a specific account (balance, items, sales)

Inputs: id (required).

get_itemC

Get details of a specific inventory item by ID

Inputs: id (required).

get_item_statsC

Get overall inventory statistics

Inputs: no named parameters.

get_saleC

Get details of a specific sale

Inputs: id (required).

list_accountsC

List vendor/consignor accounts with optional filters

Inputs: limit, cursor, is_vendor.

list_batchesC

List batches of items

Inputs: limit, cursor, status, account.

list_categoriesC

List item categories

Inputs: limit, cursor.

list_itemsC

List inventory items with optional filters. Supports filtering by price, category, account, status, location, and more.

Inputs: limit, cursor, status, category, +4 more.

list_locationsC

List store locations

Inputs: limit, cursor.

list_salesB

List sales with optional filters

Inputs: limit, cursor, status, customer, +3 more.

search_suggestC

Search across accounts and items using full-text search. Returns matching entities with their full details.

Inputs: query (required), types.

suggest_field_valuesB

Get auto-complete suggestions for a specific field (brand, color, size, tags, etc.) based on existing data.

Inputs: entity (required), field (required), value (required).

update_accountC

Update an existing account

Inputs: id (required), first_name, last_name, company, +2 more.

update_batch_statusC

Update batch status (draft or submitted)

Inputs: id (required), status (required).

update_itemC

Update an existing inventory item

Inputs: id (required), title, description, tag_price, +3 more.

void_saleC

Void a sale

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources and actions, such as create_item vs. update_item or calculate_account_metrics vs. get_account_stats. However, there is some overlap between calculate_inventory_value and get_item_stats, which both provide inventory statistics but with different focuses, potentially causing minor confusion.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern throughout, such as create_account, list_items, update_item, and calculate_sales_totals. There are no deviations in naming conventions, making the set predictable and readable for agents.

    Tool Count3/5

    With 26 tools, the count is borderline high for a consignment management system, as it may feel heavy and could lead to complexity in tool selection. While it covers many operations, a more streamlined set might improve usability without sacrificing functionality.

    Completeness5/5

    The tool surface provides comprehensive CRUD and lifecycle coverage for the consignment domain, including accounts, items, batches, categories, sales, and locations. It supports creation, retrieval, updating, deletion, listing, calculation, and analytics, with no obvious gaps that would hinder agent workflows.

    Related MCP Connectors

    Related MCP Servers