@openprints/mcp

MCP server for the OpenPrints print-on-demand API. Lets AI agents browse products, upload designs, place print orders, track shipments, and manage account balance — all through natural language.

Tools

| Tool | Description | |------|-------------| | list_products | Browse available print products and variants with pricing | | upload_design | Register a design image URL for reuse across orders | | preview_product | Preview a product with an optional design before ordering | | create_order | Place a print order — charges pre-paid balance, sends to production | | get_order_status | Check status and tracking info for an order | | cancel_order | Cancel an order and refund to account balance | | list_orders | List recent orders with optional status filter and pagination | | get_balance | Check pre-paid account balance | | topup_balance | Generate a Stripe Checkout URL to add credit |

Installation

Requirements: Node.js 18+

npm install -g @openprints/mcp

Or run directly without installing:

npx @openprints/mcp

Configuration

Two environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENPRINTS_API_KEY | Yes | — | Your OpenPrints API key (sk_test_...) | | OPENPRINTS_API_URL | No | http://localhost:3000 | Base URL of the OpenPrints API |

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openprints": {
      "command": "npx",
      "args": ["-y", "@openprints/mcp"],
      "env": {
        "OPENPRINTS_API_KEY": "sk_test_your_key_here",
        "OPENPRINTS_API_URL": "https://api.openprints.io"
      }
    }
  }
}

Or if you installed globally:

{
  "mcpServers": {
    "openprints": {
      "command": "openprints-mcp",
      "env": {
        "OPENPRINTS_API_KEY": "sk_test_your_key_here",
        "OPENPRINTS_API_URL": "https://api.openprints.io"
      }
    }
  }
}

Example workflows

Place an order from scratch:

"List available products, then order a medium white t-shirt with my logo at https://example.com/logo.png, ship to Jane Smith at 10 Downing Street, London SW1A 2AA, GB."

Check on a recent order:

"What's the status of order ord_abc123? Has it shipped yet?"

Top up balance:

"Add £50 to my OpenPrints balance."

Reuse a design across multiple orders:

"Upload my design from https://cdn.example.com/design.png, then place three orders — one for each size."

Tool reference

list_products

Returns all products with variants, SKUs, and prices.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | format | markdown | json | markdown | Response format |

upload_design

Registers a design URL. Returns a design_id for reuse.

| Parameter | Type | Description | |-----------|------|-------------| | url | string (URL) | Publicly accessible image URL (PNG, JPG, or PDF) |

preview_product

Shows product info and variants. With a design, shows a print-ready summary.

| Parameter | Type | Description | |-----------|------|-------------| | product_id | string | Product ID from list_products | | design_url | string (URL) | Optional design image URL | | design_id | string | Optional design ID from upload_design | | format | markdown | json | Response format |

create_order

Places a print order. Charges the pre-paid account balance.

| Parameter | Type | Description | |-----------|------|-------------| | product_id | string | Product ID from list_products | | design_id | string | Design ID from upload_design (use this or design_url) | | design_url | string (URL) | Design image URL (use this or design_id) | | address_name | string | Recipient full name | | address_line1 | string | Address line 1 | | address_line2 | string | Address line 2 (optional) | | address_city | string | City | | address_postcode | string | Postcode / ZIP | | address_country | string | ISO 3166-1 alpha-2 country code (e.g. GB, US) |

get_order_status

Returns status, tracking number, carrier, and shipping info.

| Parameter | Type | Description | |-----------|------|-------------| | order_id | string | Order ID from create_order | | format | markdown | json | Response format |

cancel_order

Cancels an order and refunds the amount to account balance. Irreversible.

| Parameter | Type | Description | |-----------|------|-------------| | order_id | string | Order ID to cancel |

list_orders

Lists orders with optional filtering and cursor pagination.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | status | string | — | Filter by status (in_production, shipped, delivered, cancelled, …) | | limit | number | 20 | Results per page (1–100) | | starting_after | string | — | Pagination cursor — last order_id from previous page | | format | markdown | json | markdown | Response format |

get_balance

Returns the current pre-paid account balance in pence (GBP).

No parameters.

topup_balance

Creates a Stripe Checkout session. Returns a URL the user must open in their browser to complete payment. Does not charge the card directly.

| Parameter | Type | Description | |-----------|------|-------------| | amount_cents | number | Amount to add in pence (min 100 = £1.00) | | success_url | string (URL) | Redirect URL after successful payment | | cancel_url | string (URL) | Redirect URL if payment is cancelled |

Order statuses

| Status | Meaning | |--------|---------| | payment_succeeded | Payment captured, awaiting production handoff | | in_production | Sent to ShipStation, being printed | | fulfillment_queued | ShipStation push failed, will be retried | | shipped | Dispatched — tracking number available | | delivered | Confirmed delivered | | cancelled | Cancelled before production | | refunded | Refunded after production | | disputed | Chargeback opened | | payment_failed | Payment capture failed |

Development

git clone https://github.com/openprints/mcp
cd mcp
npm install
npm run build
OPENPRINTS_API_KEY=sk_test_xxx npm start

License

MIT — see LICENSE.